swagger 生成 api 文檔 html

https://cloud.tencent.com/developer/article/1332445

 

使用Swagger2Markup實現導出API文檔

飛狗發表於 專注於主流技術和業務訂閱

2.4K

在這篇文章中：

• • 前言
  • Swagger2Markup簡介
  • 如何使用
• 騰訊雲+社區邀請

前言

在學會了如何使用Swagger之后，我們已經能夠輕松地為Spring MVC或SpringBoot的Web項目自動構建出API文檔了。但是，構建的文檔必須通過在項目中整合swagger-ui、或使用單獨部署的swagger-ui和/v2/api-docs返回的配置信息才能展現出您所構建的API文檔。本文將在使用Swagger的基礎上，再介紹一種生成靜態API文檔的方法，以便於構建更輕量部署和使用的API文檔。 Swagger使用說明：REST API文檔工具Swagger2，以及與SpringBoot的集成

Swagger2Markup簡介

Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，比如：AsciiDoc、Markdown、Confluence。

項目主頁：https://github.com/Swagger2Markup/swagger2markup

如何使用

在使用Swagger2Markup之前，我們先需要准備一個使用了Swagger的Web項目，REST API文檔工具Swagger2，以及與SpringBoot的集成。

生成AsciiDoc

生成AsciiDoc的方式有兩種：

1. 通過Java代碼來生成

第一步：編輯pom.xml增加需要使用的相關依賴和倉庫

<dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> </dependency> <repositories> <repository> <snapshots> <enabled>true</enabled> <updatePolicy>always</updatePolicy> </snapshots> <id>jcenter-releases</id> <name>jcenter</name> <url>http://jcenter.bintray.com</url> </repository> </repositories>

第二步：編寫一個單元測試用例來生成執行生成文檔的代碼

/**
     * 生成AsciiDocs格式文檔
     * @throws Exception
     */
    @Test
    public void generateAsciiDocs() throws Exception { // 輸出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://127.0.0.1:8082/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/asciidoc/generated")); } /** * 生成Markdown格式文檔 * @throws Exception */ @Test public void generateMarkdownDocs() throws Exception { // 輸出Markdown格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/markdown/generated")); } /** * 生成Confluence格式文檔 * @throws Exception */ @Test public void generateConfluenceDocs() throws Exception { // 輸出Confluence使用的格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs")) .withConfig(config) .build() .toFolder(Paths.get("./docs/confluence/generated")); } /** * 生成AsciiDocs格式文檔,並匯總成一個文件 * @throws Exception */ @Test public void generateAsciiDocsToFile() throws Exception { // 輸出Ascii到單文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/asciidoc/generated/all")); } /** * 生成Markdown格式文檔,並匯總成一個文件 * @throws Exception */ @Test public void generateMarkdownDocsToFile() throws Exception { // 輸出Markdown到單文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8082/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("./docs/markdown/generated/all")); }

以上代碼內容很簡單，大致說明幾個關鍵內容：

• MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式。除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP
• from(new URL("http://localhost:8080/v2/api-docs")：指定了生成靜態部署文檔的源頭配置，可以是這樣的URL形式，也可以是符合Swagger規范的String類型或者從文件中讀取的流。如果是對當前使用的Swagger項目，我們通過使用訪問本地Swagger接口的方式，如果是從外部獲取的Swagger文檔配置文件，就可以通過字符串或讀文件的方式
• toFolder(Paths.get("src/docs/asciidoc/generated")：指定最終生成文件的具體目錄位置 輸出到單個文件

如果不想分割結果文件，也可以通過替換toFolder(Paths.get("src/docs/asciidoc/generated")為toFile(Paths.get("src/docs/asciidoc/generated/all"))，將轉換結果輸出到一個單一的文件中，這樣可以最終生成html的也是單一的。 在執行了上面的測試用例之后，我們就能在當前項目的目錄下獲得如下內容：

image.png

可以看到，這種方式在運行之后就生成出了5個不同的靜態文件。

1. 通過Maven插件來生成

除了通過上面編寫Java代碼來生成的方式之外，swagger2markup還提供了對應的Maven插件來使用。對於上面的生成方式，完全可以通過在pom.xml中增加如下插件來完成靜態內容的生成。

<plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <sourceDirectory>./docs/asciidoc/generated</sourceDirectory> <outputDirectory>./docs/asciidoc/html</outputDirectory> <headerFooter>true</headerFooter> <doctype>book</doctype> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--菜單欄在左邊--> <toc>left</toc> <!--多標題排列--> <toclevels>3</toclevels> <!--自動打數字序號--> <sectnums>true</sectnums> </attributes> </configuration> </plugin>

配置執行命令

通過上面的配置，執行該插件的asciidoctor:process-asciidoc命令之后，就能在docs/asciidoc/html目錄下生成最終可用的靜態部署HTML了。在完成生成之后，可以直接通過瀏覽器來看查看，你就能看到類似下圖的靜態部署結果：

image.png

騰訊雲+社區邀請

我的博客即將搬運同步至騰訊雲+社區，邀請大家一同入駐：https://cloud.tencent.com/developer/support-plan?invite_code=1eyx9f4wbftcp

本文參與騰訊雲自媒體分享計划，歡迎正在閱讀的你也加入，一起分享。

發表於 2018-09-10