如何快速實現spring boot技術棧api文檔的生成

做爲開發，寫接口文檔一直是一個很頭痛的問題，尤爲在先後端分離大量盛行的當下，後端必需要爲前端同事提供明確的入參出參文檔，不然整個對接工做沒法順利進行，先後端的相愛相殺的大戲時常上演。筆者剛工做的那些年，swagger都尚未正式發佈，對接前端和app端的文檔全靠手寫markdown完成。寫接口文檔的時間經常感jio比寫代碼耗費的時間還長。隨着技術的進步和衆多開源人的努力，近幾年針對java開發的文檔生成工具愈來愈多。新入行的開發人員不再用去體會過去的那些辛酸歷程。在java文檔生成的這個領域，swagger一直是一隻領頭羊。可能佔據着90%的市場， 除此還有像 Spring REST Doc這些有名的工具也被大量的使用，可是這些工具在筆者看來使用比較蠻煩，侵入性高。今天筆者要給你們介紹和推薦一款本人開源的文檔工具smart-doc，也會介紹如何使用這個工具來生成本身的文檔。

1、當前市面上文檔工具存在的問題

下面來列舉當前市場上主流文檔工具的問題：

• 侵入性強，須要編寫大量註解，表明工具如：swagger，還有一些公司自研的文檔工具
• 強依賴性，若是項目不想使用該工具，業務代碼沒法編譯經過。
• 代碼解析能力弱，使用文檔不齊全，主要表明爲國內衆多開源的相關工具。
• 衆多基於註釋分析的工具沒法解析jar包裏面的註釋(sources jar包)，須要人工配置源碼路徑，沒法知足DevOps構建場景。
• 沒法支持多模塊複雜項目代碼分析。

2、smart-doc如何解決上述問題

• 經過分析源碼註釋自動生成API文檔，不用編寫任何註解，秉承註釋即文檔的原則，而且提供註釋強制檢查。
• smart-doc開發了smart-doc-maven-plugin插件，項目僅僅依賴插件，剔除插件無修改項目不報任何編譯錯誤。
• smart-doc在國內通過上百家企業的使用，作了不少場景的分析，解析能力很強。
• smart-doc-maven-plugin插件自動分析項目依賴，自動完成對自發布jar包和第三方jar包源碼的加載，不須要指定任何源碼路徑。
• smart-doc-maven-plugin可以識別項目依賴，多模塊maven項目不是問題。
• smart-doc文檔維護比較完善，碼雲上的wiki有16個頁面介紹各類使用方式。

關於smart-doc

3、smar-doc的不足

smart-doc並不是是完美的，仍然有不少不足。

• 界面支持不完善，沒有發送請求的頁面，沒法知足小團隊自測。
• 一些使用場景支持不完善，存在一些bug。
• 暫不支持其餘框架文檔的生成，如：dubbo等。
• 開源團隊人員少，功能實現慢。
• 當前缺少gradle插件支持。

4、spring boot集成smart-doc生成文檔。

上面說了關於一塊兒其它工具的問題，也介紹了smart-doc的優缺點，下面進入正題，如何快速使用smart-doc生成文檔。

4.1 添加插件

在spring boot項目pom中添加smart-doc的maven插件

<plugin>
	<groupId>com.github.shalousun</groupId>
	<artifactId>smart-doc-maven-plugin</artifactId>
	<version>1.0.2</version>
	<configuration>
		<!--指定生成文檔使用的配置文件-->
		<configFile>./src/main/resources/smart-doc.json</configFile>
	</configuration>
	<executions>
		<execution>
 			<!--不須要在編譯項目時自動生成文檔可註釋phase-->
			<phase>compile</phase>
			<goals>
				<goal>html</goal>
			</goals>
		</execution>
	</executions>
</plugin>

4.2 添加smart-doc.json配置文件

在4.1的代碼片斷中看到須要給插件指定一個生成文檔的配置文件smart-doc.json。文件內容以下：

{
  "serverUrl": "http://127.0.0.1",//服務器地址
  "isStrict": false,//是否用嚴格模式，嚴格模式強制檢查註釋
  "allInOne": true,//全部接口文檔合併生成到一個文檔
  "outPath": "src/main/resources/static/doc",//文檔的輸出路徑
  "projectName": "smart-doc"//指定項目名稱，用於顯示在文檔中
}

上面的幾行配置中，實際上只有outPath是必需要的，其餘都是非必須。相比其它工具，smart-doc配置簡單又不會影響到項目。想了解更多詳細配置請參考smart-doc插件使用

4.3 編寫controller接口

@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 添加用戶
     * @param user
     * @return
     */
    @PostMapping("/add")
    public User addUser(@RequestBody User user){
        return user;
    }
}

實體類：

public class User {

    /**
     * 用戶名
     */
    private String userName;

    /**
     * 暱稱
     */
    private String nickName;

    /**
     * 用戶地址
     */
    private String userAddress;

    /**
     * 用戶年齡
     */
    private int userAge;

    /**
     * 手機號
     */
    private String phone;

    /**
     * 建立時間
     */
    private Long createTime;

    /**
     * ipv6
     */
    private String ipv6;

    /**
     * 固定電話
     */
    private String telephone;
    //省略get set
}

4.4 運行插件生成文檔

效果見4.5

4.5 用戶信息操做接口

添加用戶

URL:http://localhost:8080/user/add

Type:POST

Content-Type:application/json; charset=utf-8

Request-parameters:

Parameter	Type	Description	Required	Since
userName	string	用戶名	false	-
nickName	string	暱稱	false	-
userAddress	string	用戶地址	false	-
userAge	int	用戶年齡	false	-
phone	string	手機號	false	-
createTime	number	建立時間	false	-
ipv6	string	ipv6	false	-
telephone	string	固定電話	false	-

Request-example:

{
    "userName":"鵬飛.賀",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 蕭旁7699號， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

Response-fields:

Field	Type	Description	Since
userName	string	用戶名	-
nickName	string	暱稱	-
userAddress	string	用戶地址	-
userAge	int	用戶年齡	-
phone	string	手機號	-
createTime	number	建立時間	-
ipv6	string	ipv6	-
telephone	string	固定電話	-

Response-example:

{
    "userName":"鵬飛.賀",
    "nickName":"raymond.gutkowski",
    "userAddress":"Apt. 819 蕭旁7699號， 章丘， 滇 852063",
    "userAge":41,
    "phone":"15018373016",
    "createTime":1569934393095,
    "ipv6":"9eb3:fada:ffd2:912e:6225:1062:a2d7:718f",
    "telephone":"15018373016"
}

總結

當前最新的smart-doc結合插件後，已經作到了很是易於使用，只須要引入插件和根據本身需求填充相關的配置便可，很是的輕量級。將smart-doc推薦給你們是爲了幫助更多的同行可以快速的生成api文檔，也是給一些正在自研的同行提供一些實現思路。想要參與貢獻，幫助smart-doc不斷完善的開發者，咱們也很是歡迎加入。若是您喜歡smart-doc，請記得爲咱們項目點贊，您的支持是咱們一直開源的動力！！！