前言：日常開發中經常會碰到寫接口給別人調用，寫也就罷了，還要一個完整描述的api接口使用說明，我們有沒有什麼好的工具在寫完代碼就可以出來一份api接口文檔，並且還可以測試該接口可用性呢？答案當然有，接下來就介紹今天的主角：swagger2
以下使用環境：Intellij IDEA + swagger2 2.8.0版本 + maven項目
1、首先pom文件中引入依賴包：
io.springfox
springfox-swagger-ui
2.8.0
io.springfox
springfox-spi
2.8.0
io.swagger
swagger-annotations
1.5.22
io.springfox
springfox-schema
2.8.0
io.github.swagger2markup
swagger2markup
1.3.1
ch.netzwerg
paleo-core
0.10.2
nl.jworks.markdown_to_asciidoc
markdown_to_asciidoc
1.0
2、在我們的方法上進行一些api說明，具體如何使用swagger2的一些註解說明，大家可以參考這個文章說明（https://blog.csdn.net/weixin_41846320/article/details/82970204），這裏截圖我的一個方法的說明如下：
3、接下來我們就要開始導出文檔操作了
3.1、首先我們要創建一個生成一個AsciiDocs格式文檔，測試內容方法如下：
3.2、執行該測試方法成功後，在你項目剛設置的路徑下會看到一個後綴是.adoc的文件，到這裏我們已經成功了一半了
3.3、因爲我們要生成的是.html格式的，所以我們還要在pom文件中安裝一個插件：
sourceDirectory：就是我們測試方法中那個要生成的路徑
outputDirectory：是我們要生成的html文件所存放路徑
3.4、在idea中的 Run/Debug Configurations 中，新建一個Maven Build,名字任意, Working directory爲當前工程路徑，
Command line 填寫 asciidoctor:process-asciidoc 命令，截圖如下：
3.5、執行此Maven Build,執行成功後,會在outputDirectory路徑下出現後綴是.html的文件，這就是我們要生成的html形式的API了，截圖如 下：
好了，到這裏，就算一個api接口完了，把這個靜態html文檔給前端測試等人員，一目瞭然，即使以後出現變化，咱們重新執行下測試方法，就出來新的一個api文檔，是不是很方便。