静的なドキュメントを生成する方法でSpringBoot2
実際の開発プロセスでは、我々が闊歩することにより、当社のインターフェースのドキュメントを生成することができ、この文書は、開発中のフロントエンド担当者に利用できるようになります。しかし、時には、私たちはどのように行うには、サードパーティの企業に利用できる当社のインタフェースのマニュアルを参照して、配置する必要がありますか？
私は今、この問題が発生しています。私たちのプロジェクトの開発が完了した後、分離モードは、前端と後端です。しかし、サードパーティの企業が行う方法を、私たちのインターフェイスのドキュメントがありますか？その後、我々は唯一、過去に送信することができ、静的な文書を生成、文書の闊歩する必要があります。
ドキュメントインターフェイス
インタフェースのマニュアルを言えば、我々はそれswagggerで最も精通しています。これは、簡単に注釈を付けることもやり方は、あなたが私たちに必要なことを、文書を生成することができます。そして、あなたはオンラインインターフェースをデバッグすることができます。
随着前后端分离架构和微服务架构的流行，我们使用Spring Boot来构建RESTful API项目的场景越来越多。通常我们的一个RESTful API就有可能要服务于多个不同的开发人员或开发团队：IOS开发、Android开发、Web开发甚至其他的后端服务等。
上記の後、私たちが提供するビジュアルインターフェイスに闊歩プロジェクトの開始です。
闊歩プロジェクトの統合
springboot統合闊歩は、我々は非常に単純なだけ輸入依存する必要があり、それに対してメソッドにメモを書きます。
メインクラスの追加@EnableSwagger2Doc以下のように、注釈を
プロジェクトのニーズによると、私たちは闊歩のデフォルト設定を変更することができます
swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE swagger.license=Apache License, Version 2.0 swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html swagger.termsOfServiceUrl= swagger.contact.name= swagger.contact.url= swagger.contact.email= swagger.base-package= swagger.base-path=/** アプリケーション、アクセスを起動します。http://localhost:8080/swagger-ui.html アクセスが訪問することができます
ノートは簡単です
@Api(tags = "用户管理")
@RestController
@RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下 public class UserController { // 创建线程安全的Map，模拟users信息的存储 static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>()); @GetMapping("/") @ApiOperation(value = "获取用户列表") public List<User> getUserList() { List<User> r = new ArrayList<>(users.values()); return r; } } 展開のシンプルなインターフェイスのドキュメントが終わって、次のステップは、静的です
静的インタフェースのドキュメント
Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用，比如：AsciiDoc、Markdown、Confluence。
今日は、このプラグインは、静的な機能を達成するために私たちを助けることができ、Swagger2Markup使用されています。
项目主页：https://github.com/Swagger2Markup/swagger2markup
依存追加
<dependency>
<groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> <scope>test</scope> </dependency> 今回は、<スコープ>テスト</スコープ>、これは正式な環境の中で、この依存性を取り除くことができます。
みんなの直感的に、静的を完了するために、テストクラスを作成します。
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT) public class DemoApplicationTests { @Test public void generateAsciiDocs() throws Exception { URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs"); Path outputDirectory = Paths.get("src/docs/asciidoc/generated"); // 输出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .build(); Swagger2MarkupConverter.from(remoteSwaggerFile) .withConfig(config) .build() .toFolder(outputDirectory); } } このコードの実装が完了した後、あなたは私たちがプロジェクトディレクトリに必要ASCIIDOC文書を生成することができます
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc --------paths.adoc --------security.adoc HTML生成
私たちは、ほとんど必要が見やすいようにHTMLドキュメントです。次に、ポイントのコロケーションは、それを変更する必要があります。
追加プラグインの依存関係
<plugin>
<groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory> <outputDirectory>src/docs/asciidoc/html</outputDirectory> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <toc>left</toc> </attributes> </configuration> </plugin> <バックエンド> HTML </バックエンド>このコードは、HTML文書を生成することができます。
プラグインの実行asciidoctor:process-asciidocコマンドの後には、あなたができるsrc/docs/asciidoc/html静的なHTML aの最終的な展開を生成するために使用可能なカタログ。
ドキュメントのプレビュー
それは悪いことではありません！
其实这个插件可以生成很多类型的接口文档，markdown类型也可以。大家下来，可以自己研究一下。好了，今天经验就分享到这里了。
来源：站长平台