保姆級文檔-接口平臺Yapi及接口文檔生成插件部署使用

[TOC]

前言

先來描述下背景：由于新公司業(yè)務(wù)屬于自研產(chǎn)品開發(fā)，但是發(fā)現(xiàn)各產(chǎn)品業(yè)務(wù)線對于接口文檔暫時還是通過集成Swagger來維護，準確來說是knife4j（Swagger的增強解決方案）。但是對于產(chǎn)品型開發(fā)而言，會產(chǎn)生一些如項目代碼侵入性高、版本兼容問題、文檔完全規(guī)范化較難、團隊無法在線協(xié)同等的問題。個人建議Swagger更適合用于一些對接口規(guī)范及維護要求較低的行業(yè)項目類軟件開發(fā)，相對于開發(fā)而言，接口的文檔生成及調(diào)試更加方便快捷。

所以這里結(jié)合個人之前的使用經(jīng)驗以及其他接口文檔平臺調(diào)研如下：

框架 Swagger Yapi Showdoc ApiPost
代碼侵入性 強 無 無 無
私有化部署 支持 支持 支持 不支持
是否開源 是 是 是 否
學習成本 較高 容易 容易 較高
自動生成文檔 支持 插件支持 需要客戶端 支持
數(shù)據(jù)Mock 支持 支持 不支持（需要客戶端） 支持
自動化測試 不支持 支持 需要客戶端 支持
數(shù)據(jù)導入 不支持 支持postman/swagger/har/json 不支持 支持postman
備注

當然還有其他很多可以用于接口文檔維護的，像postman、RAP、EasyAPI等平臺，文檔型的像云雀、石墨文檔、wiki等，各有優(yōu)點以及適用的業(yè)務(wù)場景。

最后決定使用支持私有部署及swagger同步導入的開源平臺 Yapi 來保存和維護各項目中的接口文檔；當然不可避免，作為無償?shù)拈_源產(chǎn)品，它也會有一些瑕疵，比如目前開源維護度低（導致社區(qū)活躍度也相對減少很多）、平臺中目錄層級不支持二級以上（需要二次開發(fā)，一些fork版本雖然支持，但是版本較低）、一些版本存在的bug（參考issue）等。

但是這些都影響不大，最重要的還是考慮公司業(yè)務(wù)及技術(shù)團隊的當前實際需求及后續(xù)擴展基本能很好的滿足。

Yapi部署-docker

首先Yapi項目由去哪兒網(wǎng)開源在GitHub，官方文檔中有詳細的相關(guān)介紹，同時也有平臺體驗地址，這里不再過多贅述。

由于公司項目中已經(jīng)使用docker來構(gòu)建環(huán)境，所以這里主要介紹如何基于docker鏡像來制作部署（非docker環(huán)境推薦官方提供的yapi-cli工具部署文檔，簡單易用，且無縫支持版本升級；而非一些博客文章，由于文章描述及水平參差不齊，可能會反向誤導）。

其實docker部署的方式跟非docker基本相差不多，只是在流程上多了一個鏡像制作，市面上也有一些博客文章也已經(jīng)介紹過了，包括一些已經(jīng)制作好并push的鏡像，但是Yapi最新的1.10版本的鏡像制作部署的文章暫時還沒有發(fā)現(xiàn)，雖然看上去大同小異，但是實際操作下來還是有一些坑的；同時自己制作的鏡像也更加放心安全。

首先我們了解到Y(jié)api的環(huán)境要求：

  • nodejs（7.6+)
  • mongodb（2.6+）

MongoDB部署

因為接口的數(shù)據(jù)使用NoSQL數(shù)據(jù)庫mongodb進行存儲，所以我們首先需要安裝部署mongodb。

1.下載官方鏡像，這里版本選擇4.2.6

docker pull mongodb:4.2.6

執(zhí)行命令docker images可以看到鏡像已經(jīng)下載完成

image-20220303144332914

2.啟動容器

 docker run  \
--name mongo \
-p 27017:27017  \
-v /data/yapi/mongodb/data/configdb:/data/configdb/ \
-v /data/yapi/mongodb/data/db/:/data/db/ \
-d mongo:4.2.6 --auth
  • -p 27017:27017：映射容器的訪問端口。
  • -v 參數(shù)：將MongoDB容器中的數(shù)據(jù)掛載到外部目錄，這樣不可預料的意外導致容器無法恢復啟動，也能保護原來的數(shù)據(jù)。
  • --auth：需要密碼才能訪問MongoDB。

使用命令docker ps可以看到容器已經(jīng)正常啟動

image-20220303143851750

3.設(shè)置用戶密碼

使用下面命令進入到容器中，并進入到MongoDB的命令行，同時切換到admin數(shù)據(jù)庫

docker exec -it mongo mongo admin
image-20220303144721422

設(shè)置一個用戶和密碼，然后驗證是否正確

db.createUser({ user:'admin',pwd:'123456',roles:[ { role:'userAdminAnyDatabase', db: 'admin'}"readWriteAnyDatabase"]});

# 驗證
db.auth('admin', '123456')
image-20220303145434787

到這里MongoDB就部署完成了，后續(xù)注意對MongoDB的數(shù)據(jù)文件定時備份就行了（相關(guān)文章很多，這里不贅述了）。

Yapi部署

部署Yapi前，我們需要自己制作docker鏡像，這里有兩種方式

  • 源碼編譯
  • 官方y(tǒng)api-cli工具

其中源碼編譯的方式稍微復雜點，對不同版本的環(huán)境依賴可能會產(chǎn)生一些坑，而且版本升級也相對麻煩點；這里推薦第二種方式，也就是yapi-cli。

1.編寫Dockerfile

vi Dockerfile

# 內(nèi)容
FROM node:11
RUN npm install -g yapi-cli --registry https://registry.npm.taobao.org

EXPOSE 3000 3000

2.編寫docker-compose

這里使用docker-compose的方式制作鏡像以及啟動部署，

vi docker-compose.yml

# 內(nèi)容
version: '3'
  
services:
  yapi:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次啟動使用
    command: "yapi server"
    # 之后使用下面的命令
    # command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次啟動時映射
      - 9091:9090
    volumes:
      - ./my-yapi:/my-yapi
  • dockerfile：執(zhí)行當前目錄下的Dockerfile來制作鏡像。
  • image：命名鏡像的名稱及tag。
  • volumes：將容器中yapi的文件掛載到外部目錄，包括配置文件。

這里注意，第一次啟動的時候需要執(zhí)行yapi-cli命令來幫助安裝，所以需要使用command: "yapi server"及- 9091:9090，安裝完成后重新執(zhí)行docker-compose前把其注釋即可。

3.制作鏡像及安裝

編寫好所需要的文件之后，執(zhí)行下面命令，

docker-compose up

首先會下載制作yapi鏡像的基礎(chǔ)鏡像node:11

image-20220303152545849

下載完成后就能看到如下控制臺，說明yapi-cli啟動完成了
image-20220303152647856

由于剛才我們將9090映射到9091端口，所以這里訪問http://192.168.24.240:9091（192.168.24.240為宿主機的ip），能看到網(wǎng)頁顯示如下，

image-20220303153127726

接下來我們直接在上面設(shè)置好然后點擊開始部署就可以安裝我們想要的版本的yapi了，之后能看到頁面以及控制臺會不停刷安裝的相關(guān)log，直到看到下面的信息這說明Yapi已經(jīng)下載安裝好了。

image-20220304095229852
image-20220304095317104

4.啟動

到這里就剩最后一步，下面我們直接退出控制臺停止運行，由于之前- ./my-yapi:/my-yapi已經(jīng)將Yapi文件掛載出來了，用ls命令能查看到當前目錄下的my-yapi文件，

image-20220304100040570

進入目錄后能看到config.json文件，它是Yapi的基礎(chǔ)配置文件，可以設(shè)置管理員賬號、MongoDB連接配置、郵箱通知等等，具體參考官方文檔。

接下來修改docker-compose.yml如下，


version: '3'

services:
  yapi:
    build:
      context: ./
      dockerfile: ./Dockerfile
    image: yapi:1.10.2
    container_name: yapi
    # 第一次啟動使用
    # command: "yapi server"
    # 之后使用下面的命令
    command: "node /my-yapi/vendors/server/app.js"
    ports:
      - 3000:3000
      # 第一次啟動時映射
      # - 9091:9090
    volumes:
      - ./my-yapi:/my-yapi

修改完成后保存退出，使用下面命令就可以直接啟動了，

docker-compose up -d
  • -d：后臺啟動

啟動完成后，使用docker ps，能看到我們的Yapi容器已經(jīng)啟動完成了,

image-20220304100727872

同時使用命令docker images也能看到我們制作好的1.10.2的鏡像文件，

image-20220304100827557

5.訪問

啟動完成后我們?yōu)g覽器直接訪問http://192.168.24.240:3000就能看到如下，

image-20220304101028469

接下來我們就用之前配置的管理員賬戶以及默認密碼ymfe.org登錄使用即可。

一些使用建議：

  1. 由管理員或各項目負責人添加不同項目分組，以及添加分組成員；
  2. 項目分組下以項目迭代版本來分類新建項目，通過項目命名攜帶版本號作為區(qū)分。
  3. 測試集合可以用于開發(fā)用例自測包括流程自動化測試，實際對于測試人員需求可能不太滿足。

接口文檔生成插件

雖然Yapi已經(jīng)接管接口文檔平臺，滿足開發(fā)團隊對文檔的維護需求了，但是我們知道大多數(shù)使用Swagger的開發(fā)可能最關(guān)注的點就是通過注解會自動生成接口文檔，無需手動編寫，提高了工作效率。

因為Yapi平臺開放了相關(guān)API，所以同樣支持外部生成，由于目前公司開發(fā)人員基本使用IDEA作為開發(fā)工具，暫時只調(diào)研了一些支持IDEA的插件。

綜合使用及對比幾個IDEA插件后，像YapiUpload、EasyYapi、Yapi X等，發(fā)現(xiàn)EasyApi插件的配置支持相對友好、文檔生成時代碼基本無侵入性、自定義功能強大等，同時滿足項目接口文檔生成較高的規(guī)范化需求；雖然自定義功能使用門檻較高，但是項目一次配置后基本無需改動，更多自定義規(guī)則配置及功能的詳細使用請參考官網(wǎng)文檔。

使用步驟：

  1. 打開File/Settings/Plugins搜索EasyYapi，選擇install后重啟IDEA;

    image-20220304132339622

  2. 打開File/Other Settings/EasyApi,在Yapi下配置server和tokens：

server 即部署的Yapi地址，如：http://192.168.20.24:3000
tokens 即yapi項目中用于請求項目openapi的私有token，獲取方式為項目->設(shè)置->token 配置 -> 工具標識

  1. 三種生成接口文檔并上傳到Y(jié)api的方式（初次使用可能會以彈窗的方式要求輸入token）：
    • 打開項目中的包含api的文件或者在IDEA的左邊項目文件區(qū)域選擇文件或者文件夾 鼠標右鍵點擊文件內(nèi)容或文件夾, 選擇ExportYapi 導出該文件或文件夾中所有的api;
    • 打開項目中的包含api的文件或者在IDEA的左邊項目文件區(qū)域選擇文件或者文件夾 使用快捷鍵alt shift E(windows)/ctrl E(mac) 然后選擇要導出的API,選擇導出渠道Yapi 點擊[?]按鈕或者按回車鍵完成導出
    • 鼠標點擊最上方Code > YapiDashBoard 然后就可以用鼠標將左邊的API拖動到右邊yapi目錄中，完成API導出到Y(jié)api

注意要生成相對規(guī)范的接口文檔，需要編寫較為完整的代碼注釋，如下(簡單的注釋Demo)：

/**
 * 分類名稱
 * 分類備注/描述
 */
@RestController
@RequestMapping(value = "/demo")
public class DemoController {

    /**
    * api名稱
    * api描述
    * @param param1 參數(shù)1的名稱或描述
    * @param param2 參數(shù)2的名稱或描述
    * @return
    */
    @GetMapping(value = "/test")
    public Result<Demo> methodName1(@RequestParam String param1,
                                    @RequestParam(required = false, defaultValue = "1") Integer param2){
        ...
    }

}

public class Demo {
    /**
     * 字段注釋
     */
    private Long field1;
    /**
     * 如果使用javax.validation的話
     * 可以使用@NotBlank/@NotNull表示字段必須
     */
    private String field2;

    ...
}

通過插件上傳后，即可在平臺目錄中看到所生成的接口文檔。

使用建議：

  1. 通過插件來自動生成的接口文檔需要自行查看生成的文檔是否正確且規(guī)范，不正確或不規(guī)范的地方需要手動編輯修正。

  2. 一些全局的配置，可以在項目或模塊目錄下新建.yapi.config來進行配置(更對配置參考官方文檔)

    # 參數(shù)忽視特定類
param.ignore=@java.lang.String
# 參數(shù)描述后綴
param.doc=groovy:",類型<"+tool.uncapitalize(it.type().name().replace("java.lang.","").replace("Long","String")) +">"
# Long轉(zhuǎn)String
json.rule.convert[java.lang.Long]=java.lang.String
# 統(tǒng)一返回體
method.return[#return]=groovy: "com.xxx.xxx.Result<" + it.returnType() +">"

參考文檔：
https://github.com/Ryan-Miao/docker-yapi

身未動，心已遠。

把一件事做到極致就是天分！

最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

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

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