Swagger之外的選擇
今天給大家安利一款接口文檔生成器——JApiDocs。
swagger想必大家都用過吧,非常方便,功能也十分強大。如果要說swaager有什麼缺點,想必就是註解寫起來比較麻煩。如果我說有一款不用寫註解,就可以生成文檔的工具,你心動了嗎?他就是我們今天的主角——JApiDocs。
下面我們一起來看看如何使用!
一、添加依賴
<dependency>
<groupId>io.github.yedaxia</groupId>
<artifactId>japidocs</artifactId>
<version>1.3</version>
</dependency>
二、配置生成參數
我們新建一個項目,然後隨便寫一個main方法,增加生成文檔的配置,然後運行main方法。
DocsConfig config = new DocsConfig();
config.setProjectPath("F:\\Java旅途\\japi-docs"); // 項目根目錄
config.setProjectName("japi-docs"); // 項目名稱
config.setApiVersion("V1.0"); // 聲明該API的版本
config.setDocsPath("F:\\test"); // 生成API 文檔所在目錄
config.setAutoGenerate(Boolean.TRUE); // 配置自動生成
Docs.buildHtmlDocs(config); // 執行生成文檔
三、編碼規範
由於JApiDocs是通過解析Java源碼來實現的,因此如果要想實現想要的文檔,還是需要遵循一定的規範。
3.1 類註釋、方法註釋和屬性註釋
如果我們想生成類的註釋,我們可以直接在類上加註釋,也可以通過加@description來生成。
/**
* 用戶接口類
*/
@RequestMapping("/api/user")
@RestController
public class UserController {}
/**
* @author Java旅途
* @Description 用戶接口類
* @Date 2020-06-15 21:46
*/
@RequestMapping("/api/user")
@RestController
public class UserController {}
如果我們想生成方法的註釋,只能直接加註釋,不能通過加@description來生成。
/**
* 查詢用戶
* @param age 年齡
* @return R<User>
*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){
User user = new User("Java旅途", 18);
return R.ok(user);
}
JApiDocs可以自動生成實體類,關於實體類屬性的註釋有三種方式,生成的效果都是一樣的,如下:
/**
* 用戶名稱
*/
private String name;
/**
* 用戶年齡
*/
private int age;
// 用戶名稱
private String name;
// 用戶年齡
private int age;
private String name;// 用戶名稱
private int age;// 用戶年齡
他除了支持咱們常用的model外,還支持IOS的model生成效果如下:
3.2 請求參數
如果提交的表單是 application/x-www-form-urlencoded
類型的key/value
格式,則我們通過@param註解來獲取參數,在參數後面添加註釋,示例如下:
/**
* @param age 年齡
*/
@GetMapping("/list")
public R<User> list(@RequestParam int age){
User user = new User("Java旅途", 18);
return R.ok(user);
}
生成的文檔效果如下:
請求參數
參數名 | 類型 | 必須 | 描述 |
---|---|---|---|
age | int | 否 | 年齡 |
如果提交的表單是 application/json
類型的json
數據格式,如下:
/**
* @param user
* @return
*/
@PostMapping("/add")
public R<User> add(@RequestBody User user){
return R.ok(user);
}
生成的文檔效果如下:
請求參數
{
"name": "string //用戶名稱",
"age": "int //用戶年齡"
}
3.3 響應結果
我們知道,如果
Controller
聲明了@RestController
,SpringBoot會把返回的對象直接序列成Json數據格式返回給前端。 JApiDocs也利用了這一特性來解析接口返回的結果,但由於JApiDocs是靜態解析源碼的,因此你要明確指出返回對象的類型信息,JApiDocs支持繼承、泛型、循環嵌套等複雜的類解析。
因此我們不需要再寫註釋,它會根據我們的返回結果進行解析,效果如下:
返回結果:
{
"code": "int",
"msg": "string",
"data": {
"name": "string //用戶名稱",
"age": "int //用戶年齡"
}
}
最終,我們生成的接口文檔,如下:
四、高級配置
4.1 @ApiDoc
如果你不希望把所有的接口都導出,我們可以在配置中設置config.setAutoGenerate(Boolean.FALSE);然後再想要生成的接口上添加@ApiDoc。
@ApiDoc有以下三個屬性:
- result: 這個可以直接聲明返回的對象類型,如果你聲明了,將會覆蓋SpringBoot的返回對象
- url: 請求URL,擴展字段,用於支持非SpringBoot項目
- method: 請求方法,擴展字段,用於支持非SpringBoot項目
@ApiDoc(result = User.class, url = "/api/user/view", method = "post")
4.2 @Ignore
如果你不想導出對象裏面的某個字段,可以給這個字段加上@Ignore
註解,這樣JApiDocs導出文檔的時候就會自動忽略掉了。
public class User {
@Ignore
private int age;
}
五、總結
JApiDocs就介紹到這裏了,優勢劣勢大家很容易就看出來了。幾乎不需要註釋即可生成接口文檔,僅有的幾個註釋我們也可以通過ide來自動生成。但是JApiDocs不具備swagger在線調試功能。如果有一天JApiDocs支持在線調試后,那時候肯定會有一大波追隨者,畢竟寫代碼的誰喜歡寫多餘的註解!~
本站聲明:網站內容來源於博客園,如有侵權,請聯繫我們,我們將及時處理
【其他文章推薦】
※廣告預算用在刀口上,台北網頁設計公司幫您達到更多曝光效益
※新北清潔公司,居家、辦公、裝潢細清專業服務
※別再煩惱如何寫文案,掌握八大原則!
※教你寫出一流的銷售文案?
※超省錢租車方案
※FB行銷專家,教你從零開始的技巧