springboot將接口內容快速生成接口文檔導出,swagger將api文檔以表格文檔導出

我們開發工作中,經常需要面對寫文檔的事情.后端寫給前端,甲方給乙方提供技術接口文檔.有時候會覺得挺麻煩.

雖然swagger已經為我們提供了不少便利,但通常對外提供文檔時,人們希望接口參數等內容,是以表單形式展現的,比如:

 

 於是我找到了將swagger轉為類似這種表格參數展示的Swagger2Markup.它的使用也比較簡單方便.基本可以滿足需要.

下面是我對這個Swagger2Markup使用的代碼地址:https://github.com/OceanBBBBbb/swaggerdoc

可以直接把這個在內網部署一套,而不必為所有項目添加Swagger2Markup..因為只要輸入swagger-doc的地址,就可以導出這個項目的API文檔了.

 

根據swagger訪問路徑,導出完整規范的接口文檔

說明

如果只是需要嵌入已存在的swagger項目， 加上maven配置，加入test里的Swagger2Doc.java修改url就可以了。
實現轉換使用的是Swagger2Markup

引入Swagger2Markup

<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.3</version>
</dependency>

　　

這時候執行測試類內容時，通常會報一個錯。如相關jar包不存，如

NoClassDefFoundError: ch/netzwerg/paleo/ColumnIds$StringColumnId

　　

等等，官方給的解釋一般是，加上：

<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

　　

如果沒解決，我這就是這個情況，可以把上面的repositories內容改為：

<repositories>
    <repository>
        <id>spring-libs-milestone</id>
        <url>https://repo.spring.io/libs-milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <!-- jhipster-needle-maven-repository -->
</repositories>
<pluginRepositories>
    <pluginRepository>
        <id>spring-plugins-release</id>
        <url>https://repo.spring.io/plugins-release</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

　　

編寫測試類

可以直接用這里的測試目錄里的Swagger2Doc.java，還可以根據Swagger2Markup 的說明做一些個性化的修改。

如何使用swaggerdoc

（后面准備在加上轉word、pdf等格式，加上docker方便快速部署）
啟動swaggerdoc后，訪問http://localhost:8080

正常將看到如圖頁面，輸入可訪問的swagger-api文檔地址，注意是這個一般后綴為api-docs的可以訪問到 文檔json內容的地址。而不是swagger-ui.html這個。如

然后選擇文檔類型：
* Markdown: 就是熟悉的README.MD格式，拿到后，導入到Markdown編輯器即可。
* Confluence: wiki格式，在Confluence中使用時，導入為wiki格式。
* AsciiDocs: 這個我也不知道在哪用。

可以看一下Markdown的效果：

和

Confluence的效果（截圖內容都是冰山一角）