[[398313]]

最近前端們一直反映Swagger看接口信息非常不爽，于是我花了倆小時把Swagger干掉，用上了傳說中更好用的YApi。今天就簡單分享一下心得體會。

Swagger與YApi

其實我個人認為Swagger也沒啥不好的，后端集成起來方便快捷，就是UI不行，而且對于Java來說代碼的侵入性太高了。

swagger界面

YApi除了解決了這些問題之外還具有權限管理、團隊協作、自動化測試、支持OpenApi規范等等。

YApi界面

YApi區別于Swagger的最大不同就是YApi需要導入文檔(雖然它也可以通過Swagger輪詢導入)，而Swagger可以自動發現。

安裝這里就不細說了，官方文檔說的很清楚。你可以選擇命令行部署、可視化部署，也能使用Docker部署。

推薦內網部署，畢竟大部分API文檔比較敏感。

文檔注釋

YApi的文檔解析基于Java注釋規范，沒有代碼侵入!但是這就要求我們要按照Javadoc的規范進行書寫文檔注釋，這是使用YApi的前提。一個接口文檔分為以下幾個部分。

接口類注釋

接口類的注釋，下面是基本的格式。第一行會作為菜單展示，盡量短小精悍;第二行是接口的描述，用來描述接口的作用和細節。

/** 
 * 接口分類名稱 
 * <p> 
 * 接口備注/描述 
 * 
 * @author felord 
 * @since v1.0 
 */ 
@RestController 
@RequestMapping("/foo") 
public class FooController { 
// 省略 
} 

還有@module、@copyright什么的其實可以不寫。

參數注釋

入參和出參的注釋，配合JSR-303有奇效哦。

/** 
 * 賬戶基本信息 
 *  
 * @author felord 
 * @since v1.0 
 */ 
@Data 
public class UserInfoDetail { 
 
    /** 
     * 用戶名 
     * 
     * 配合JSR303注解聲明此字段的約束方式【必填】 
     */ 
    @NotBlank 
    private String username; 
    /** 
     * 真實姓名 
     */ 
    private String realName; 
    /** 
     * 手機號碼 
     */ 
    private String phoneNumber; 
    /** 
     * 性別 -1 未知 0 女性 1 男性 
     * 
     * 使用@see來說明該字段的取值來源 
     * @see GenderType#value() 
     */ 
    private Integer gender; 
    /** 
     * 昵稱 
     */ 
    private String nickName; 
    /** 
     * 微信號 
     * 使用{@code Deprecated} 表示字典將來會廢棄 
     */ 
    @Deprecated 
    private String wechatAccount; 
    /** 
     * 電子信箱 
     */ 
    private String email; 
} 

接口方法注釋

入參為復雜對象的話注釋用@link引用，@RequestBody會指定Content-Type為application/json。

/** 
 * 新增用戶信息 
 * 
 * @param userInfoDetail 用戶信息參數 {@link UserInfoDetail} 
 * @return {@link Boolean} 
 */ 
@PostMapping("/bar") 
public boolean detail(@RequestBody UserInfoDetail userInfoDetail) { 
    return true; 
} 

Post請求對應的樣式

如果參數是原始類型類型或者String,可以這樣寫，@RequestParam有奇效。

/** 
 * 獲取用戶信息 
 * 
 * @param name 姓名 
 * @param age  年齡 
 * @return {@link UserInfoDetail} 
 */ 
@GetMapping("/sam") 
public UserInfoDetail detailBySamples(@RequestParam String name, Integer age) { 
    return new UserInfoDetail(); 
} 

Get請求對應的樣式

導入文檔

YApi支持Swagger、Postman、JSON等方式導入文檔。不過我個人更喜歡使用插件導入，Intellij IDEA中推薦使用easy-yapi。導入的時候定位到對應的Controller,使用快捷鍵Alt+Ins呼出快捷菜單。

呼出快捷菜單

選擇Export Yapi ，首次選擇會讓你輸入YApi的服務器地址，還會讓你輸入對應項目的token字符串。

token 字符串

依次填入后，就會解析生成文檔并同步到YApi服務器了，結果就是上面截圖中的樣子。然后你可以配置權限分配給組員使用了，如果有文檔更新重復上面的步驟即可，YApi提供了幾種策略，你可以選擇覆蓋也可以選擇不覆蓋。YApi提供了比Swagger更豐富的功能，具體我還在探索中，如果有什么好玩的，會在后面分享給大家，還請多多關注。

本文轉載自微信公眾號「碼農小胖哥」，可以通過以下二維碼關注。轉載本文請聯系碼農小胖哥公眾號。