EasyYapi注釋生成接口文檔，無入侵拋棄swagger第一步

前言

每個(gè)后端開發(fā)人員都有寫文檔的經(jīng)歷。從最開始的手寫到配置swagger寫文檔或者其他相關(guān)jar包等。但是、閱讀了這篇文章，你會(huì)發(fā)現(xiàn)一個(gè)寫文檔的新世界?。?！不開玩笑，讀完你就會(huì)把swagger當(dāng)球踢！??！

  • 本篇文章已Spring boot為例

  • 該方法無任何代碼入侵！似的，沒有任何代碼入侵沒有看錯(cuò)

  • 可以使用PostMan或者md展示。似的，它還能已json的形式導(dǎo)入PostMan。還能直接轉(zhuǎn)成MD文檔。但這不是重點(diǎn)！往下看

  • 怎么辦，我以前用得是swagger還能改嗎？---> 當(dāng)然可以，它還能導(dǎo)入swagger數(shù)據(jù)，不過這不重要 ---> 為什么呢？ ---> 說啦是注釋寫文檔了，只要注釋寫的好，都不是問題

  • 這么神奇，到底是個(gè)什么呢？---> idea插件啦。似的，插件！為什么沒有代碼入侵了？ 因?yàn)橹皇莻€(gè)插件，沒有任何滑稽配置

  • 文章結(jié)尾追加mock各種用法以及一些注釋小方法（必看）

解決方案

1.入正題,打開idea設(shè)置，找插件EasyYapi

下載、重啟

2.idea配置就基本完成了、似得完成了，沒想到吧。官方網(wǎng)站 ，當(dāng)然這只是簡(jiǎn)單配置

3.簡(jiǎn)單用法、先說明轉(zhuǎn)成PostMan和md用法、比較簡(jiǎn)單。

4.新建一個(gè)接口類，寫好注釋！?。?重點(diǎn)、注釋要寫好，但也沒那么復(fù)雜

  • 接口類
/**
 * 測(cè)試類專用接口
 *
 * @author zmj
 * @date 2021-1-4
 */
@RestController
@RequestMapping(value = "/go")
public class AppController {


    /**
     * 數(shù)據(jù)、測(cè)試接口
     *
     * @param bean
     * @return
     */
    @PostMapping(value = "/test")
    public RestBean test(@RequestBody IdBean bean) {
        return null;
    }


}
  • 實(shí)體類
import javax.validation.constraints.NotNull;  //注意這個(gè)NotNull包是javax的才能識(shí)別

public class IdBean {


    /**
     * 需要查詢的公司id
     * @mock 10295      //枚舉用 @see 包名路徑+類   ---> 個(gè)人看官網(wǎng)
     */
    @NotNull
    private int id = -1;


    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }
}
  • 實(shí)體類(自己寫的返回類、可以用泛型指示！似得可以用泛型指示，別問我什么是泛型?。?！)

/**
 * 用戶、響應(yīng)體
 * 2020-12-1
 */
public class RestBean<T> {

    //返回、結(jié)果
    private int result;

    //返回、信息
    private String message;

    //返回、值
    private T data;

    /**
     * 代碼、類型設(shè)置
     *
     * @param type
     */
    public void setType(RestCodeType type) {
        this.result = type.getCode();
        this.message = type.getMessage();
    }


    /**
     * 設(shè)置數(shù)據(jù)
     *
     * @param data
     */
    public void setData(T data) {
        this.result = RestCodeType.SUCCESS.getCode();
        this.message = RestCodeType.SUCCESS.getMessage();
        this.data = data;
    }


    public T getData() {
        return data;
    }


    public int getResult() {
        return result;
    }

    public String getMessage() {
        return message;
    }
}

5.接口類已經(jīng)搞定了，接下里是如何生成接口了--->快捷鍵 alt+shift+e

操作1

6.這就是需要生成文檔的接口列表(左側(cè)菜單快捷鍵直接全局掃描所有接口)，掃描了當(dāng)前類的所有接口。同時(shí)注釋小窗口的下拉列表有三種 Yapi(后面講)、postman、md文檔(沒什么好說的)，這里直接
先講postman導(dǎo)入

7.選擇postman、導(dǎo)出到某個(gè)位置（導(dǎo)出成功后是一個(gè)json，不局限于postman）,打開postman


步驟一
步驟二
步驟三

8.導(dǎo)入完成。（這還不是重點(diǎn)）

image.png

9.主要到這個(gè)@mock了嗎？還有我代碼里的注釋了嗎？

image.png

10.很遺憾postMan不能使用mockjs生成數(shù)據(jù)，難過...

11.不過沒關(guān)系，接下來才是文檔的重點(diǎn)--->YApi登場(chǎng)(不收費(fèi)，放心甚至是開源了?。?！)

Yapi使用文檔

  • 直接上成果圖，沒圖先講就是耍流氓?。?！
圖片一
圖片二

1.Yapi用到的環(huán)境和工具 node.js mongodb 除此之外...沒了

2.node.js直接百度下載安裝，沒什么可以說的。（新手去百度下）

3.npm i -g yapi-cli yapi的自動(dòng)化安裝工具 官方，安裝比較簡(jiǎn)單，是在不懂可以百度，文檔不多但是也不少

4.mongodb安裝，這個(gè)數(shù)據(jù)庫(kù)安裝比較簡(jiǎn)單，下載安裝運(yùn)行完事（新手百度）

5.成型頁(yè)面(可以多人組隊(duì))

image.png

6.創(chuàng)建一個(gè)Yapi項(xiàng)目

7.回到代碼、快捷鍵--->這次選擇Yapi，確認(rèn)。這時(shí)候需要輸入兩個(gè)東西，一個(gè)是地址一個(gè)是token，地址是yapi網(wǎng)頁(yè)地址（個(gè)人配置的），token如圖


image.png

8.確認(rèn)上傳即可。

Ps

  • 可能有些東西沒在上面講清楚。
  • easyYapi識(shí)別的是注釋，下面舉例
  • 實(shí)體類、接口需要的那種(可以在Yapi項(xiàng)目中添加的參數(shù)值)
    //它是一個(gè)ID
    String id;

 
    String id;  //這樣也是一個(gè)ID


    /**
     * 這樣也是一個(gè)ID
     * @mock 可以理解為給參數(shù)定值(這就是值)
     * @see  填枚舉類的值(路徑+類名),例com.xxx.xxx.類 --->枚舉值
     */
    String id;
  • 接口類
/**
 * 分類
 * 描述(注意行數(shù))
 * @author 作者
 * @ignore 此標(biāo)注會(huì)被忽略，方法同理
 * @date 日期   養(yǎng)成好習(xí)慣
 */
public class AppController


    /**
     * 接口名稱
     * 描述
     * @undone （未完成接口標(biāo)識(shí)，默認(rèn)完成）
     * @menu 分類
     * @return
     */
 @PostMapping(value = "/識(shí)別這種接口，看官網(wǎng)")
 public 可以用泛型<類> name(@RequestBody 提交參數(shù)類 bean)

追加Mock與其他小方法

  • 忽略對(duì)象小方法1，fastjson序列化不生效
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.google.gson.annotations.Expose;

...

@JsonIgnore    //二選一(spring boot 使用jackson序列化)
@Expose(serialize = true)  // 二選一，建議前者
private int obj； //在接口中我會(huì)被忽略-注意值也會(huì)被忽略掉
  • 忽略對(duì)象小方法2，jackson序列化不生效
...
private transient int obj； //在接口中我會(huì)被忽略-注意值也會(huì)被忽略掉,transient 關(guān)鍵字
...
  • 對(duì)象修改名稱小方法
import com.google.gson.annotations.SerializedName;

...

@SerializedName("jbo")
private int obj； //在接口中我叫jbo
  • mock的 @natural方法
 /**
  * 字段
  * @mock @natural(0,10000)      //自然數(shù)范圍對(duì)象
  */
private int obj;
  • mock的@pick方法
 /**
  * 字段
  * @mock @pick(中文,非中文)      //隨機(jī)挑選一個(gè)
  */
private String obj;
  • mock的@date方法
 /**
  * 字段
  * @mock @date      //隨機(jī)日期，如1978-05-30
  */
private String obj;
  • mock的@timestamp方法
 /**
  * 字段
  * @mock @timestamp  //時(shí)間戳 秒   mtimestamp有問題不記錄替代方案@timestamp@string("0",3)
  */
private long obj;
  • mock的@boolean、@float、@Interage、@string方法
 /**
  * 字段
  * @mock @boolean   //隨機(jī)變量，后兩則相似
  */
private boolean   obj;


 /**
  * 字段
  * @mock @float(3,9)  //隨機(jī)浮點(diǎn)范圍
  */
private double obj;

 /**
  * 字段
  * @mock @string("lower",1,8)  //隨機(jī)范圍字符串 @string(3) 長(zhǎng)度三位的隨機(jī)字符串 @string("123",3) 在123字符池隨機(jī)三位
  */
private String obj;
  • 完結(jié)、撒花、喜歡的點(diǎn)贊
最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請(qǐng)聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請(qǐng)結(jié)合常識(shí)與多方信息審慎甄別。
平臺(tái)聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡(jiǎn)書系信息發(fā)布平臺(tái)，僅提供信息存儲(chǔ)服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

友情鏈接更多精彩內(nèi)容