springboot swagger生成文檔

Swagger 生成html api文檔

---

測試過程發現使用插件生成swagger.json一直失敗，下載官方示例卻是正常，各種配置都檢查過沒有發現問題所在，目前沒有解決，僅作爲學習，暫時沒有去深究其原因。

---

通過方法生成

• 生成過程

接口生成原理:
    1)使用Springfox-swagger2生成swagger.json文件
    2)使用Swagger2markup將swagger.json文件轉換成asciidoc文檔片段，包括（definitions.adoc、overview.adoc、paths.adoc、security.adoc）
    3)編寫asciidoc的文檔(主要是組裝步驟2中生成的asciidoc文檔片段)
    4)使用Asciidoctor將asciidoc轉換成HTML或pdf

• 引入pom依賴

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.21</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.21</version>
        </dependency>

        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup-maven-plugin</artifactId>
            <version>1.3.3</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj</artifactId>
            <version>1.5.4.1</version>
            <scope>test</scope>
        </dependency>

• 執行GenerateHtml測試方法

通過插件生成

很遺憾，發現springboot項目無論如何也無法生成正常的swagger.json，但是我們可以使用代碼來生成

• 生成過程

1）生成swagger.json
2) 生成snippets
3）將asciidoc生成html、pdf

• 相關配置

參考pom.xml

通過插件生成

git示例中的項目使用的是JAX-RS，經測試也是正常

• 生成過程

1）生成swagger.json
2) 自定義adoc模板
3）將生成的snippets與模板結合
4）生成html文檔

• 引入插件

swagger-maven-plugin

• 參考

官網示例
源碼