API文檔管理工具

時間 2019-11-09

標籤 api 文檔管理工具简体版

原文原文鏈接

系統龐大以後，先後端分離開發，前端調用後端提供的接口，請求協議通常是 HTTP，數據格式通常是 JSON。後臺只負責數據的提供和計算，而徹底不處理展示邏輯和樣式；前端則負責拿到數據，組織數據並展示的工做。這樣結構清晰，關注點分離，先後端會變得相對獨立並鬆耦合。好處多多。html

可是這樣帶來不少問題，前端可能須要拿到後端的數據以後，才能開始開發工做，等前端開發完成以後，而後再與後端一塊兒聯調。耗時不說，若是業務的需求更改，後端接口變動，怎麼快速便捷告知前端的開發人員？還有其餘如文檔維護和及時更新的問題。這樣一來，編寫文檔也是個不小的負擔。前端

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

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

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

swagger

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

Swagger提供的工具：c++

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

springboot 集成 swagger

添加@Configuration & @EnableSwagger2 註解的配置類git

@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();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("freemarker project RESTful APIs")
                .description("this is freemarker app swagger-ui page")
                .version("1.1")
                .build();
    }
}

pom.xml 添加：github

<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>

參考GitHubweb

經常使用註解
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 git@github.com: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

一、建立 MongoDB 數據卷
docker volume create mongo_data_yapi
二、啓動 MongoDB
docker run -d --name mongo-yapi -v mongo_data_yapi:/data/db mongo
三、獲取 YApi 鏡像，並打 tag

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

四、初始化 YApi 數據庫索引及管理員帳號

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

五、啓動 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": "admin@admin.com",
  "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