你還在用 Swagger？試試這個神器！

今天給大家安利一款接口文檔生成器——JApiDocs。

swagger想必大家都用過吧，非常方便，功能也十分強大。如果要說swagger有什么缺點，想必就是注解寫起來比較麻煩。如果我說有一款不用寫注解，就可以生成文檔的工具，你心動了嗎？他就是我們今天的主角——JApiDocs。

下面我們一起來看看如何使用！

一、添加依賴

  io.github.yedaxia  japidocs  1.3

二、配置生成參數(shù)

我們新建一個項目，然后隨便寫一個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); // 執(zhí)行生成文檔

三、編碼規(guī)范

由于JApiDocs是通過解析Java源碼來實現(xiàn)的，因此如果要想實現(xiàn)想要的文檔，還是需要遵循一定的規(guī)范。

3.1 類注釋、方法注釋和屬性注釋

如果我們想生成類的注釋，我們可以直接在類上加注釋，也可以通過加@description來生成。

/** * 用戶接口類 */@RequestMapping("/api/user")@RestControllerpublic class UserController {}
/** * @author Java旅途 * @Description 用戶接口類 * @Date 2020-06-15 21:46 */@RequestMapping("/api/user")@RestControllerpublic class UserController {}

如果我們想生成方法的注釋，只能直接加注釋，不能通過加@description來生成。

/** * 查詢用戶 * @param age 年齡 * @return R*/@GetMapping("/list")public R 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 請求參數(shù)

如果提交的表單是 application/x-www-form-urlencoded 類型的key/value格式，則我們通過@param注解來獲取參數(shù)，在參數(shù)后面添加注釋，示例如下：

/**  * @param age 年齡  */@GetMapping("/list")public R list(@RequestParam int age){    User user = new User("Java旅途", 18);    return R.ok(user);}

生成的文檔效果如下：

請求參數(shù)

如果提交的表單是 application/json 類型的json數(shù)據(jù)格式，如下：

/**  * @param user  * @return  */@PostMapping("/add")public R add(@RequestBody User user){    return R.ok(user);}

生成的文檔效果如下：

請求參數(shù)

{  "name": "string //用戶名稱",  "age": "int //用戶年齡"}

3.3 響應結果

?

我們知道，如果Controller聲明了@RestController，SpringBoot會把返回的對象直接序列成Json數(shù)據(jù)格式返回給前端。JApiDocs也利用了這一特性來解析接口返回的結果，但由于JApiDocs是靜態(tài)解析源碼的，因此你要明確指出返回對象的類型信息，JApiDocs支持繼承、泛型、循環(huán)嵌套等復雜的類解析。

?

因此我們不需要再寫注釋，它會根據(jù)我們的返回結果進行解析，效果如下：

返回結果：

{  "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就介紹到這里了，優(yōu)勢劣勢大家很容易就看出來了。幾乎不需要注釋即可生成接口文檔，僅有的幾個注釋我們也可以通過ide來自動生成。

但是JApiDocs不具備swagger在線調(diào)試功能。如果有一天JApiDocs支持在線調(diào)試后，那時候肯定會有一大波追隨者，畢竟寫代碼的誰喜歡寫多余的注解！~