Swagger之外的選擇

Java旅途發表於2020-06-22
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支援線上除錯後，那時候肯定會有一大波追隨者，畢竟寫程式碼的誰喜歡寫多餘的註解！~

相關文章