springboot 和swagger整合後，導出MARKDOWN、CONFLUENCE靜態文本

在和前端的接口交互過程中，經常要給他們提供接口的api，api參數、參數類型，api返回結構和類型等信息，在之前一直都是手寫mock給他們，然後在confluence中做格式化處理，在這個過程中，發現格式化過程特別費時間，不停地複製粘貼，操作多了之後容易眼花 -。-。

不能一直做重複勞動，我就去找了下怎麼講swagger的接口數據導出為靜態文檔。由於公司項目用的是springboot，所以和swagger集成後，肯定可以通過ip+端口的方式訪問swagger，但對於前端來說，他們不太會用，接口一多，他們也就蒙了，再加上，服務重啟過程中是不能看swagger的，所以還是導出來靜態文檔能加快前端開發效率，也能減少前端來找我們諮詢的時間。

好了，上代碼。

前置，確認你的springboot項目已經和swagger做好了整合,如果沒有，通過下面第一步中的pom依賴和我的代碼截圖可以實現整合。

我的端口為8090，那麼通過如下url

http://localhost:8090/swagger-ui.html

至此，說明你本地的swagger已經生效。

下面是開始做導出：

第一步，在pom中添加依賴：（請嚴格按照我的依賴，否則容易出現版本問題，導致導出失敗）

<code><dependency>
\t\t\t<groupid>io.springfox/<groupid>
\t\t\t<artifactid>springfox-swagger2/<artifactid>
\t\t\t<version>2.6.0/<version>
\t\t/<dependency>
\t\t<dependency>
\t\t\t<groupid>io.springfox/<groupid>
\t\t\t<artifactid>springfox-swagger-ui/<artifactid>
\t\t\t<version>2.6.0/<version>
\t\t/<dependency>
\t\t<dependency>
\t\t\t<groupid>io.github.swagger2markup/<groupid>
\t\t\t<artifactid>swagger2markup/<artifactid>
\t\t\t<version>1.3.1/<version>
\t\t/<dependency>
\t\t<dependency>
\t\t\t<groupid>io.swagger/<groupid>
\t\t\t<artifactid>swagger-core/<artifactid>
\t\t\t<version>1.5.16/<version>
\t\t/<dependency>
\t\t<dependency>
\t\t\t<groupid>io.swagger/<groupid>
\t\t\t<artifactid>swagger-models/<artifactid>
\t\t\t<version>1.5.16/<version>
\t\t/<dependency>/<code>

第二步：

創建單元測試，生成MARKDOWN格式的輸出

<code>@SpringBootTest
public class SwaggerExport {
    /**
     * 生成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:8090/v2/api-docs"))
                .withConfig(config)
                .build()
                //toFile會將多個文件整合成為一個，toFolder會拆分成多個文件
                .toFile(Paths.get("./docs/markdown/generated"));
    }
}
/<code>

生成文件為：

至此，就可以提供一個可以用的文件給前端了，下面的步驟是生成html文件

第一步，生成asciiDoc

<code>    /**
     * 生成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();
        //設置swagger-api的json來源
        Swagger2MarkupConverter.from(new URL("http://localhost:8090/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("./docs/asciidoc/generated"));//設置生成文件的路徑
    }/<code>

生成文檔：

第二步在pom中添加maven插件

<code><plugin>
\t\t\t\t<groupid>org.asciidoctor/<groupid>
\t\t\t\t<artifactid>asciidoctor-maven-plugin/<artifactid>
\t\t\t\t<version>1.5.6/<version>
\t\t\t\t<configuration>
\t\t\t\t\t
\t\t\t\t\t<sourcedirectory>docs/asciidoc/generated/<sourcedirectory>
\t\t\t\t\t
\t\t\t\t\t<outputdirectory>docs/asciidoc/html/<outputdirectory>
\t\t\t\t\t<backend>html/<backend>
\t\t\t\t\t<sourcehighlighter>coderay/<sourcehighlighter>
\t\t\t\t\t<attributes>
\t\t\t\t\t\t
\t\t\t\t\t\tleft
\t\t\t\t\t\t
\t\t\t\t\t\t
\t\t\t\t\t\t
\t\t\t\t\t\t<sectnums>true/<sectnums>
\t\t\t\t\t/<attributes>
\t\t\t\t/<configuration>
\t\t\t/<plugin>/<code>

第三步：運行插件，截圖中的高亮部分

運行結果

打開html，結果如下：

通過上述步驟，就可以生成swagger靜態文檔，MARKDOWN和HTML兩種版本。

在我的例子中，可以看到有多個controller接口，如果你只想處理一個或者指定幾個，可以這樣配置：

或者指定路徑

希望這篇文章能幫到你，如果方便的話，麻煩幫忙點擊下廣告，您的支持是我不斷更新的動力！

閱讀更多 JP同學的分享 的文章

關鍵字: 參數 格式化 接口