API文檔管理工具

系統龐大之后，前后端分離開發，前端調用后端提供的接口，請求協議一般是 HTTP，數據格式一般是 JSON。后台只負責數據的提供和計算，而完全不處理展現邏輯和樣式；前端則負責拿到數據，組織數據並展現的工作。這樣結構清晰，關注點分離，前后端會變得相對獨立並松耦合。好處多多。

但是這樣帶來很多問題，前端可能需要拿到后端的數據之后，才能開始開發工作，等前端開發完成之后，然后再與后端一起聯調。耗時不說，如果業務的需求更改，后端接口變更，怎么快速便捷告知前端的開發人員？還有其他如文檔維護和及時更新的問題。這樣一來，編寫文檔也是個不小的負擔。

此時就需要一個在線接口文檔平台/工具，提供接口的請求參數 requestBody 和響應參數 responseBody 的數據結構定義。但是僅僅有 requestBody 和 responseBody 的數據結構還是不行的，前端調用后端的接口時沒有響應數據（接口還沒有開發好），前端並不能開始干活。故而我們進一步要求這些工具具備模擬出真實數據的能力，即所謂的 mock server功能，暫時替代后台服務，這樣方便前端聯調。

考慮到文檔及時更新的負擔，將文檔寫在代碼里，開發人員編寫代碼時同時修改文檔。然后通過工具從代碼中抽出文檔，並生成方便用戶閱讀的格式。此類工具早已存在，比如Java中的 javadoc，其他諸如：swagger、apiDoc。

這類工具真的不要太多，到底哪個好用上手方便安裝簡單還真是眾口難調的問題，而且需要試用一段時間才有感覺和感受，有時間成本在里面。不過，一般看團隊看架構師的選擇。

swagger

官網：https://swagger.io/
Swagger 是一款RESTful 接口的文檔在線自動生成+功能測試功能軟件，一個規范和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務，讓部署管理和使用功能強大的API 變得簡單。swagger，提供一種從項目代碼中自動生成接口文檔的功能，可以保持和代碼的同步變化。通過 Swagger 你可以獲得項目的一種交互式文檔，客戶端SDK的自動生成等功能。

Swagger提供的工具：

• Swagger Core：Swagger-core 是 Swagger的Java 實現，核心實現；
• Swagger Codegen：提供根據swagger的接口定義文件(yaml形式)，以一種命令行工具的形式，直接生產相應的代碼；
• Swagger Editor：使用 yaml 語言先定義簡單的接口，然后通過 Swagger-codergen 就可以自動生成相應的服務端和客戶端的調用代碼；

springboot 集成 swagger

添加@Configuration & @EnableSwagger2 注解的配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("fm.web"))
                .paths(PathSelectors.any())
                .build();
    }
<span class="token keyword"><span class="hljs-function"><span class="hljs-keyword"><span class="hljs-function"><span class="hljs-keyword">private</span></span></span></span></span><span class="hljs-function"><span class="hljs-function"> ApiInfo </span></span><span class="token function"><span class="hljs-function"><span class="hljs-title"><span class="hljs-function"><span class="hljs-title">apiInfo</span></span></span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params"><span class="hljs-function"><span class="hljs-params">(</span></span></span></span></span><span class="token punctuation"><span class="hljs-function"><span class="hljs-params"><span class="hljs-function"><span class="hljs-params">)</span></span></span></span></span><span class="hljs-function"><span class="hljs-function"> </span></span><span class="token punctuation">{</span>
    <span class="token keyword"><span class="hljs-keyword"><span class="hljs-keyword">return</span></span></span> <span class="token keyword"><span class="hljs-keyword"><span class="hljs-keyword">new</span></span></span> <span class="token class-name">ApiInfoBuilder</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">title</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"freemarker project RESTful APIs"</span></span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">description</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"this is freemarker app swagger-ui page"</span></span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">version</span><span class="token punctuation">(</span><span class="token string"><span class="hljs-string"><span class="hljs-string">"1.1"</span></span></span><span class="token punctuation">)</span>
            <span class="token punctuation">.</span><span class="token function">build</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

}

   
   
   
           

pom.xml 添加：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.9.2</version>
 </dependency>

   
   
   
           

參考GitHub

常用注解
TODO: 待整理。
使用ApiImplicit
Params描述多個參數
(2) 使用ApiImplicitParam時，需要指定paramType,這樣也便於swagger ui 生成參數的輸入格式。
paramType 有五個可選值 ： path, query, body, header, form

ApiImplicitParam 與 ApiParam 的區別
ApiImplicitParam: This is the only way to define parameters when using Servlets or other non-JAX-RS environments。
對Servlets或者非 JAX-RS的環境，只能使用 ApiImplicitParam。
在使用上，ApiImplicitParam比ApiParam具有更少的代碼侵入性，只要寫在方法上就可以了，但是需要提供具體的屬性才能配合swagger ui解析使用。
ApiParam只需要較少的屬性，與swagger ui配合更好。
ModelAttribute 是Spring mvc的注解，這里Swagger可以解析這個注解，獲得User的屬性描述。

Swagger2Markup

主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，比如：AsciiDoc、Markdown、Confluence。基於Swagger，生成靜態API文檔，以便於構建更輕量部署和使用的API文檔。
開源主頁：https://github.com/Swagger2Markup/swagger2markup

Swagger Editor

有在線版 https://editor.swagger.io/
也可以本地安裝：

git clone [e-mail]:swagger-api/swagger-editor.git
cd swagger-editor
npm install
npm start
npm install -g http-server #安裝服務器
unzip swagger-editor.zip #解壓
http-server swagger-editor #啟動swagger-editor
# 訪問http://localhost:8080 即可看到。

   
   
   
           

契約測試

所以，在一開始就定一個契約就成迫在眉睫的事情，雙方就API相關的內容，包括路徑、參數、類型等達成一致，當然，這份契約並不是一旦創建就不能修改的，而且，如果一開始沒有設計好，很有可能會頻繁的修改。這個時候，要讓雙方都能夠實時的跟蹤最新的API就成了一個難題。還好，在總結前人的經驗和教訓之后，早已有應對之策，那就是契約測試。
首先，我們先假設我們已經有了一份契約；然后，前端會根據這份契約建立一個Mock server，所有的測試都發往這個Mock server。有兩方面的原因：一是這個時候可能后台的API還沒有開發完成；二是有可能因為網絡等其他方面的原因導致直接調用真實的后台API會很不穩定或者很耗時。如果后台的API實現和之前約定的並不一樣，怎么能保證到集成的時候雙方還能很順利的集成呢？只需要讓前端的測試定期連接真實的API執行一遍就能盡早的發現差異性。相應的測試和契約定義就需要更新以滿足最新的業務需求。
總之，進行契約測試的目的就是盡早的發現差異性，並作出調整，將最后集成的風險降到最低。

對 swagger 的吐槽：
耦合性太強，重復的注解信息？

YApi

簡介 & 特性

官方網站：https://yapi.ymfe.org/index.html
Github地址：https://github.com/YMFE/yapi
YApi 由 YMFE 開源，旨在為開發、產品、測試人員提供更優雅的接口管理服務，可以幫助開發者輕松創建、發布、維護 API。
特性

• 基於 Json5 和 Mockjs 定義接口返回數據的結構和文檔，效率提升多倍；
• 免費開源，內網部署，信息不會泄露；
• 權限管理，扁平化權限設計，即保證大型企業級項目的管理和易用性，滿足各類企業的需求；
• 可視化接口管理 基於 websocket 的多人協作接口編輯功能和類 postman 測試工具，讓多人協作成倍提升開發效率；
• Mock Server 易用的 Mock Server， 除支持普通的隨機 mock 外，還增加 Mock 期望功能，根據設置的請求過濾規則，返回期望數據；
• 自動化測試 完善的接口自動化測試，支持對 Response 斷言，保證數據的正確性；
• 數據導入 支持導入 swagger, postman, har 數據格式，方便遷移舊項目；
• 插件機制 強大的插件機制，滿足各類業務需求；

YMFE——去哪兒大前端團隊 & 移動架構組，由FE，iOS和Android工程師共同組成。

安裝

使用 Docker 安裝 YApi

1、創建 MongoDB 數據卷
docker volume create mongo_data_yapi
2、啟動 MongoDB
docker run -d --name mongo-yapi -v mongo_data_yapi:/data/db mongo
3、獲取 YApi 鏡像，並打 tag

docker pull registry.cn-hangzhou.aliyuncs.com/anoy/yapi
docker tag registry.cn-hangzhou.aliyuncs.com/anoy/yapi yapi

   
   
   
           

4、初始化 YApi 數據庫索引及管理員賬號

docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /api/vendors \
  yapi \
  run install-server

   
   
   
           

5、啟動 YApi 服務：

docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /api/vendors \
  -p 3000:3000 \
  yapi \
  server/app.js

   
   
   
           

安裝成功，訪問地址 http://localhost:3000

CentOS 系統安裝

# 安裝 Node.js
curl --silent --location https://rpm.nodesource.com/setup_8.x | sudo bash -
yum -y install nodejs
# 安裝編譯工具包
yum install gcc-c++ make -y
# 安裝配置MogoDB數據庫
cd /etc/yum.repos.d/
vim mongodb.repo

   
   
   
           

[mongodb]
name=MongoDB Repository
baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64/
gpgcheck=0
enabled=1

yum install mongodb-org -y
# 啟動服務
service mongod start
ps -ef|grep mongod
lsof -i :27017
# 創建數據庫
mongo

   
   
   
           

命令：

use yapi
db.wong.insert({“name”:“kenny wong”})
show dbs
db.createUser(‘yapi’,‘yapi321’)

# 安裝YApi 軟件
mkdir yapi
cd yapi/
git clone https://github.com/YMFE/yapi.git vendors
cp config_example.json ../config.json
vim config.json

   
   
   
           

{
  "port": "3000",
  "adminAccount": "[e-mail]",
  "db": {
    "servername": "127.0.0.1",
    "DATABASE":  "yapi",
    "port": 27017,
    "user": "yapi",
    "pass": "yapi321"
  },
  "mail": {
    "enable": true,
    "host": "smtp.163.com",
    "port": 465,
    "from": "***@163.com",
    "auth": {
        "user": "***@163.com",
        "pass": "*****"
    }
  }
}

   
   
   
           

npm install --production --registry https://registry.npm.taobao.org
# 啟動服務
npm run install-server
node server/app/js
# 或者以后台服務形式運行
node server/app/js &

   
   
   
           

apiDoc

官網：http://apidocjs.com/
apiDoc是一個非常輕量級的，適用於幾乎所有流行語言的，針對Restful API的文檔自動生成工具。文檔寫在注釋里面，apiDoc基於NodeJS實現，提供歷史版本比較功能。
安裝：npm install apidoc -g
文檔生成：apidoc -i src -o dest，該命令從當前工作目錄的src子目錄下讀取所有代碼文件，並從中抽取apiDoc的文檔注釋，然后生成HTML格式的文檔，並保存在dest子目錄下。

API Blueprint

官網 https://apiblueprint.org/
語法類似 markdown；在 https://apiblueprint.org/tools.html 頁面搜索下載一個工具，比如 snowboard， https://github.com/bukalapak/snowboard， 這個頁面就是最好的文檔：

# 參考 GitHub 頁面給出的安裝指引：linux下安裝，安裝最新版 v1.7.0 版
wget https://github.com/subosito/snowboard/releases/download/v1.7.0/snowboard-v1.7.0.linux-amd64.tar.gz
tar -zxvf snowboard-v1.7.0.linux-amd64.tar.gz
./snowboard -h

   
   
   
           

restdocs

JApiDocs

銜接前后端開發的的工具，實現代碼即文檔，持續集成接口測試的小目標。在前后端協作中的一個問題，即使有完善的 API 文檔，在接口沒有開發出來之前，要進行接口的測試，只能本地或者通過一些平台（rap）去模擬接口生成相關數據，這對於前端開發人員來說也是一個額外的負擔。
示例：
特性

• 深度集成 spring boot；
• 支持生成 Java 等語言的 Response 模型代碼；
• 支持接口聲明過時(@Deprecated)，方便的文檔目錄等；
• 支持自定義代碼生成模板；
• 以一個 Controller 作為一組接口導出到一個 Html 文件中；
• 支持一般的 Java Web 工程，需要在相關方法添加額外的路由；

官網：
示例：https://yedaxia.me/play-apidocs/
GitHub：https://github.com/YeDaxia/JApiDocs

對比

API 工具	文檔支持	語言支持	接口測試
swagger	功能強大，學習成本高，維護成本高	多語言	支持
apiDoc	學習成本一般，維護成本高	多語言	不支持
JApiDocs	代碼即文檔，學習和維護成本低	Java	支持發布到 RAP

參考：
Yapi
API文檔自動生成工具apiDoc簡介

原文地址：https://blog.csdn.net/lonelymanontheway/article/details/83177403

                                </div>