Swagger以外的選擇

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

swagger想必你們都用過吧，很是方便，功能也十分強大。若是要說swaager有什麼缺點，想必就是註解寫起來比較麻煩。若是我說有一款不用寫註解，就能夠生成文檔的工具，你心動了嗎？他就是咱們今天的主角——JApiDocs。

下面咱們一塊兒來看看如何使用！

1、添加依賴

<dependency>
  <groupId>io.github.yedaxia</groupId>
  <artifactId>japidocs</artifactId>
  <version>1.3</version>
</dependency>

2、配置生成參數

咱們新建一個項目，而後隨便寫一個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); // 執行生成文檔

3、編碼規範

因爲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、高級配置

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;
}

5、總結

JApiDocs就介紹到這裏了，優點劣勢你們很容易就看出來了。幾乎不須要註釋便可生成接口文檔，僅有的幾個註釋咱們也能夠經過ide來自動生成。可是JApiDocs不具有swagger在線調試功能。若是有一天JApiDocs支持在線調試後，那時候確定會有一大波追隨者，畢竟寫代碼的誰喜歡寫多餘的註解！~