摘要：其標(biāo)準(zhǔn)為前身是，提供強(qiáng)大的在線編輯功能，包括語法高亮錯(cuò)誤提示自動(dòng)完成實(shí)時(shí)預(yù)覽，并且支持用戶以格式撰寫導(dǎo)入導(dǎo)出轉(zhuǎn)換文檔。

團(tuán)隊(duì)內(nèi)部RestAPI開發(fā)采用設(shè)計(jì)驅(qū)動(dòng)開發(fā)的模式，即使用API設(shè)計(jì)文檔解耦前端和后端的開發(fā)過程，雙方只在聯(lián)調(diào)與測(cè)試時(shí)耦合。在實(shí)際開發(fā)和與前端合作的過程中，受限于眾多因素的影響，開發(fā)效率還有進(jìn)一步提高的空間。本文的目的是優(yōu)化工具鏈支持，減少一部分重復(fù)和枯燥的勞動(dòng)。

需求理解：前后端先理解產(chǎn)品思路、需求的詳細(xì)內(nèi)容

敲定接口：后端出API設(shè)計(jì)文檔初稿，與前端面對(duì)面或者在線討論修正，接著后端（有時(shí)是前端）把API描述記錄到公司內(nèi)部的API文檔庫（在線markdown編輯器，提供分級(jí)目錄的存儲(chǔ)功能，對(duì)如何描述API沒有一定的標(biāo)準(zhǔn)，因此描述格式不統(tǒng)一，因人而異¹）。接著根據(jù)雙方工作的安排，約定聯(lián)調(diào)時(shí)間

獨(dú)立開發(fā)：雙方獨(dú)立開發(fā)（也有可能非完全獨(dú)立開發(fā)，如需要對(duì)方的環(huán)境配合等；或者存在返工，如API設(shè)計(jì)發(fā)生變更等）

系統(tǒng)聯(lián)調(diào)：測(cè)試API基本功能和雙方系統(tǒng)的連通性

測(cè)試回歸：開發(fā)或者QA編寫測(cè)試用例并測(cè)試業(yè)務(wù)流程

根據(jù)個(gè)人的開發(fā)經(jīng)驗(yàn)，后端編寫API設(shè)計(jì)文檔時(shí)常見的情況有：如果是簡單的需求，API數(shù)量較少，后端直接通過內(nèi)部即時(shí)通信軟件和前端溝通；如果是復(fù)雜的需求，API數(shù)量較多，后端會(huì)先把API描述寫到本地臨時(shí)文檔（純文本、markdown、evernote等）或者內(nèi)網(wǎng)（內(nèi)部個(gè)人Wiki、git倉庫）中，然后把鏈接發(fā)給前端review或者直接面對(duì)面溝通。這樣的方式靈活，但存在一些問題，比如：

描述格式?jīng)]有標(biāo)準(zhǔn)。對(duì)于簡單的描述，文檔格式比較隨意，雙方基于約定和經(jīng)驗(yàn)理解和開發(fā)¹；完備的描述，編寫文檔所需時(shí)間較長，并且細(xì)節(jié)復(fù)雜（需要考慮不同的HTTP請(qǐng)求類型、HTTP頭部信息、HTTP請(qǐng)求內(nèi)容等），高質(zhì)量地創(chuàng)建這份文檔本身就是件非常吃力的事，下游的抱怨聲不絕于耳。當(dāng)然在合作開發(fā)中，文檔越完備，雙方的理解偏差就越少、開發(fā)產(chǎn)生的bug就越少，后期也更容易維護(hù)代碼、適應(yīng)人員變更，但是編寫完備的文檔所需要的額外時(shí)間也不容忽視，沒有代碼產(chǎn)出的設(shè)計(jì)文檔可能不得已讓位于現(xiàn)實(shí)中整體開發(fā)時(shí)間的緊張。

以開發(fā)“獲得管理員賬戶下可用商戶”為例。如果是簡單的描述，后端告知前端url為{host}/ajax/shop，返回的結(jié)構(gòu)是[{"shopId":int,"shopName":string}]，有經(jīng)驗(yàn)的前端會(huì)自動(dòng)判斷出Method為Get，Content-type為application/json，request不需要附帶參數(shù)，不需要對(duì)錯(cuò)誤值做特殊處理；而如果是復(fù)雜的描述，后端一般會(huì)列出API名稱、功能描述、調(diào)用方式、請(qǐng)求參數(shù)、請(qǐng)求示例、返回值、成功的返回結(jié)果示例、失敗的返回結(jié)果示例中的幾項(xiàng)，填充到已有的API模板中2。

輸入效率不高。由于開發(fā)的API模板缺乏固定的標(biāo)準(zhǔn)，因此只能在例如Wiki、純文本編輯器、markdown編輯器中編寫，無法得到現(xiàn)代IDE中語法高亮、自動(dòng)補(bǔ)全、錯(cuò)誤提示等特性的支持，整體感覺就像是在記事本中寫Java。

設(shè)計(jì)文檔中會(huì)規(guī)定API輸出的數(shù)據(jù)結(jié)構(gòu)（一般為json數(shù)組或者json對(duì)象），如果數(shù)據(jù)結(jié)構(gòu)較為復(fù)雜（比如包含有幾十個(gè)字段的POJO），要在設(shè)計(jì)文檔中書寫可讀性良好的數(shù)據(jù)結(jié)構(gòu)需要更多的時(shí)間；如果數(shù)據(jù)結(jié)構(gòu)中字段缺失或者可讀性差，則會(huì)影響前端的文檔理解和代碼開發(fā)。

如果后端能提供樣例數(shù)據(jù)自然是最好的，因?yàn)楹蠖俗钍煜I(yè)務(wù)邏輯，產(chǎn)生的樣例數(shù)據(jù)比前端自己Mock的數(shù)據(jù)更好。但是復(fù)雜數(shù)據(jù)結(jié)構(gòu)的樣例數(shù)據(jù)的編寫同樣很花時(shí)間。

> 舉例：需求要求開發(fā)一個(gè)新增優(yōu)惠券API，其樣例數(shù)據(jù)只能由開發(fā)手動(dòng)生成。如果是修改已有的API，要補(bǔ)充新的樣例數(shù)據(jù)，開發(fā)一般會(huì)登錄商戶平臺(tái)，打開優(yōu)惠券頁面，在Chrome中實(shí)際操作一遍，抓包得到request的body（json格式），在json格式化網(wǎng)站（如[json.cn](json.cn)）美化后復(fù)制到API設(shè)計(jì)文檔中。![clipboard.png](/img/bVTWta)

重復(fù)錄入。因?yàn)槲臋n庫功能羸弱，使用不便，所以開發(fā)一般先按自己的格式寫一份文檔，但是如果不直接把API錄入到公司文檔庫，則開發(fā)需要對(duì)一份API出兩份設(shè)計(jì)文檔。開發(fā)一般會(huì)開兩個(gè)窗口，左邊是API設(shè)計(jì)文檔的完成件，右邊是公司API文檔庫編輯頁面，然后把左邊格式各異的API描述文本轉(zhuǎn)換到右邊統(tǒng)一的markdown格式。

例如：想象一下從Wiki文檔的表格中一個(gè)個(gè)復(fù)制粘貼，再編輯成markdown格式文本是典型的成本大于收益的工作。

文檔維護(hù)成本大。由于文檔和代碼分開存放，由于需要手動(dòng)操作，因此文檔與代碼同步成本較高。隨著時(shí)間推移，不斷修改接口實(shí)現(xiàn)的時(shí)候都必須同步修改接口文檔，而文檔與代碼又處于兩個(gè)不同的媒介，除非有嚴(yán)格的管理機(jī)制，不然很容易導(dǎo)致不一致現(xiàn)象，并在業(yè)務(wù)整體交接、開發(fā)成員替換時(shí)使后來人付出較大的時(shí)間成本。

不同的存放形式的優(yōu)缺點(diǎn)見仁見智，類似于Spring也有XML和JavaConfig兩種配置方式。

缺少樣例數(shù)據(jù)。由于團(tuán)隊(duì)內(nèi)部前端一般不會(huì)全面的了解業(yè)務(wù)，后端提供的樣例數(shù)據(jù)往往比前端自己生成的Mock數(shù)據(jù)對(duì)業(yè)務(wù)需求的把握更準(zhǔn)確。如果后端能在API設(shè)計(jì)文檔中提供樣例數(shù)據(jù)，一是如果前端沒有自動(dòng)Mock工具的話，能節(jié)約前端生成Mock數(shù)據(jù)的時(shí)間；二是能在聯(lián)調(diào)前為前端提前發(fā)現(xiàn)一些低級(jí)錯(cuò)誤（比如具有業(yè)務(wù)特征的一些默認(rèn)值處理、空值處理、字段缺失等場(chǎng)景）。

beta環(huán)境綁定了唯一的beta域名，因此在多分支并行開發(fā)時(shí)是稀缺資源，較大的項(xiàng)目在beta環(huán)境編譯和部署往往消耗很多等待和解決沖突的時(shí)間。如果在聯(lián)調(diào)中發(fā)現(xiàn)的問題較多，就需要多次部署beta環(huán)境，時(shí)間成本十分可觀。

如何減少部署時(shí)間另外行文

總結(jié)起來，上面列出的問題大部分是由于API描述標(biāo)準(zhǔn)不統(tǒng)一引起的，因此要用標(biāo)準(zhǔn)化的工廠代替散亂的手工生產(chǎn)。雖然平時(shí)開發(fā)的API具有Rest風(fēng)格、對(duì)外網(wǎng)開放，只被企業(yè)自己的應(yīng)用調(diào)用，不過普遍的WebAPI開發(fā)流程還是適用的。我在網(wǎng)上搜索一些功能較為符合的RestAPI設(shè)計(jì)工具，將其大致分為3類討論。

人和機(jī)器可讀的API描述標(biāo)準(zhǔn)，圍繞該語言有完善的工具鏈：一般有設(shè)計(jì)、編譯（即Codegen）、測(cè)試（有MockServer、自動(dòng)Mock、本地直連等形式）、文檔（包括靜態(tài)文檔，如html和pdf；還有可交互文檔html+js）、合作（多人+多角色合作開發(fā)）這幾個(gè)模塊，各個(gè)標(biāo)準(zhǔn)都差不多。

較為學(xué)術(shù)性的表述：雖然Web API的實(shí)現(xiàn)正變得越來越普及，但在工具方面還缺乏一些被廣泛接受的標(biāo)準(zhǔn)，用以描述、發(fā)現(xiàn)，并且理解大量基于API的服務(wù)的意義。Web API之“元語言”有三個(gè)關(guān)鍵領(lǐng)域：API描述、API發(fā)現(xiàn)以及API檔案。所謂的API描述，指的是以一種讓人類與機(jī)器都可讀的形式對(duì)API進(jìn)行描述，包括API的實(shí)現(xiàn)細(xì)節(jié)，例如資源與URL、表述格式（HTML、XML、JSON等等）、狀態(tài)碼以及輸入?yún)?shù)。
Swagger、Apiary、RAML的格式各自采取了一種略有不同的設(shè)計(jì)方式，但在本質(zhì)上都提供了相同的基本特性：以多種不同級(jí)別的細(xì)節(jié)對(duì)Web API進(jìn)行描述。

以Swagger2³為例，分為5個(gè)部分（示例圖來自于RAML，不過功能都差不多）。

Design：其標(biāo)準(zhǔn)為OpenAPI（前身是Swagger API Spec），提供強(qiáng)大的在線編輯功能，包括語法高亮、錯(cuò)誤提示、自動(dòng)完成、實(shí)時(shí)預(yù)覽⁴，并且支持用戶以Json、Yaml格式撰寫⁵、導(dǎo)入、導(dǎo)出、轉(zhuǎn)換文檔。

Build：設(shè)計(jì)文檔可以編譯成客戶端和服務(wù)端，支持的語言包括Java、NodeJS、C++等主流語言。其中Java服務(wù)器端使用流行的Spring Boot構(gòu)建，生成的代碼包括定義的API接口、空實(shí)現(xiàn)方法的樣板代碼、業(yè)務(wù)POJO、配套的Swagger注解。值得注意的是，由自動(dòng)生成的Swagger注解，可以反向生成最初的API設(shè)計(jì)文檔

Test：可在本地服務(wù)器運(yùn)行時(shí)使用本地測(cè)試功能；用戶也可以使用SwaggerHub中提供收費(fèi)的在線測(cè)試功能，主要有MockServer（Auto Mocking）、問題跟蹤（Issue Tracking）

Document：可以在線或離線（包括代碼編譯時(shí)和運(yùn)行時(shí)）地生成靜態(tài)html、pdf等文檔；SwaggerHub可以配合API版本，自動(dòng)同步相應(yīng)文檔的版本

Share：SwaggerHub提供團(tuán)隊(duì)管理、聯(lián)調(diào)開發(fā)、文檔標(biāo)注等多人合作開發(fā)的支持

再提一下Apiary和RAML。Apiary⁶使用API Blueprint標(biāo)準(zhǔn)，Apiary網(wǎng)站提供了在線編輯、實(shí)時(shí)預(yù)覽、Mock、可交互文檔、團(tuán)隊(duì)合作、Github同步、流量追蹤等包含整個(gè)API生命周期的所有服務(wù)，當(dāng)然這是收費(fèi)產(chǎn)品，而且價(jià)格不菲；另外，用戶也可以通過開源的命令行工具進(jìn)行離線的API設(shè)計(jì)、文檔生成、發(fā)布過程，并將其集成到自己的工作流中，這也是它的一大特點(diǎn)。RAML使用RAML1.0標(biāo)準(zhǔn)，沒有自己的可視化在線開發(fā)平臺(tái)，而是用官方或第三方的離線工具（如API Workbench系列）來代替，因此它也存在一些缺點(diǎn)，比如：工具更新不及時(shí)，某些Tool不支持最新的RAML1.0。

類似于Intellij Idea的生成JavaDoc功能，是一種注釋解析器，從C++、Java、Python代碼注釋中基于特定的關(guān)鍵字（如@param、@return）生成API靜態(tài)文檔。由于更像是先代碼實(shí)現(xiàn)后生成API文檔，所以不能算作是設(shè)計(jì)驅(qū)動(dòng)的開發(fā)；另外apidocjs也缺乏IDE支持。

沒有公開的API設(shè)計(jì)語言，提供在線或離線、閉源或開源的可視化、一體化API開發(fā)平臺(tái)。這里選擇中文的Rap、eolinker作為代表。Rap是阿里的開源作品，也提供線上服務(wù)，核心功能是文檔編輯和自動(dòng)Mock服務(wù)。eolinker是綜合的接口管理平臺(tái)，除了常見的功能，還提供接口商店、數(shù)據(jù)字典等適合創(chuàng)業(yè)團(tuán)隊(duì)快速開發(fā)API的特性。在此不做進(jìn)一步介紹。

社區(qū)活躍、功能完善，應(yīng)用成熟。

學(xué)習(xí)成本低、上手時(shí)間短。作為業(yè)務(wù)開發(fā)，缺少時(shí)間熟悉學(xué)習(xí)曲線陡峭的知識(shí)和工具。

功能較多地契合上述優(yōu)化方向。

能補(bǔ)充現(xiàn)有工作流的不足，不做大范圍的代替。

要考慮測(cè)試環(huán)境處于內(nèi)網(wǎng)造成的障礙。

rap、eolinker、swaggerHub、apiary提供了一整套API開發(fā)環(huán)境，取代了現(xiàn)有工作流。放棄。

apidocjs缺乏現(xiàn)代IDE特性支持，輸入效率較低。放棄。

綜合考慮，最后選擇Swagger2。因?yàn)镾wagger對(duì)現(xiàn)有的工作流侵入較少；工具較為完整；與團(tuán)隊(duì)使用的Spring MVC技術(shù)棧無縫集成，可以減輕文檔工作量。Swagger2也有一些缺點(diǎn)，如：使用注解方式對(duì)代碼有侵入性。

減少文檔的編寫時(shí)間

如果后端先編寫?yīng)毩⒌腁PI設(shè)計(jì)文檔，可利用Swagger在線編輯器或IDE插件的自動(dòng)完成等特性；yaml格式統(tǒng)一、簡單易懂、表達(dá)能力強(qiáng)，較markdown冗余字符更少。通過模仿官方Example很容易學(xué)習(xí)OpenAPI規(guī)定的關(guān)鍵字。

另外后端也可以把API設(shè)計(jì)文檔直接通過注解的形式，標(biāo)注在Controller類和相關(guān)方法上（以Spring MVC和Spring Boot為例），即可以通過Java反射在Maven Complie或運(yùn)行時(shí)生成API設(shè)計(jì)文檔。Swagger有Intellij Idea的插件支持，Swagger注解則能利用現(xiàn)代Java IDE的特性，提高輸入效率；另外完善的注解也方便其他開發(fā)人員進(jìn)行后期維護(hù)，不需要在設(shè)計(jì)文檔和代碼實(shí)現(xiàn)中來回切換查看。此種方式相當(dāng)于面向規(guī)約的開發(fā)模式，即先規(guī)定接口，再填充實(shí)現(xiàn)。

減少文檔的轉(zhuǎn)換時(shí)間：利用第三方工具實(shí)現(xiàn)從Swagger、API Blueprint、RAML格式的互相轉(zhuǎn)換，或者直接輸出為html靜態(tài)文檔，方便整合到現(xiàn)在的工作流中。比如：API Blueprint的markdown格式可以存儲(chǔ)到公司的API文檔庫，html靜態(tài)文檔可以存儲(chǔ)到內(nèi)部Wiki。

減少（可能的）開發(fā)時(shí)間：如果已有獨(dú)立的API設(shè)計(jì)文檔，在Swagger Editor中生成基于Maven + Spring Boot的服務(wù)端代碼，不過生成的POJO和Controller類的命名可能不太理想，需要自己調(diào)整。

減少聯(lián)調(diào)時(shí)間：后端可以在設(shè)計(jì)文檔或注解中指定API或者POJO的Example數(shù)據(jù)，節(jié)約前端手動(dòng)編寫Mock數(shù)據(jù)的時(shí)間。

先建立RestController類、相應(yīng)的API空方法、POJO作為骨架。對(duì)應(yīng)的API設(shè)計(jì)文檔見文末的Reference節(jié)。

@Api("Users")
@RestController
@RequestMapping(value = "/users")
public class UserController {
    @ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)User對(duì)象創(chuàng)建用戶")
    @PostMapping
    public String postUser(@RequestBody User user) {
        return null;
    }
    @ApiOperation(value = "獲取用戶詳細(xì)信息", notes = "根據(jù)url的id來獲取用戶詳細(xì)信息")
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return null;
    }    
}
class User{
    private Long id;
    private String name;
    private String age;
    //getter,setter
}

生成的具體方式按照耗時(shí)長短排列為：Maven Complie、Test Case、Server Runtime。可在Swagger Editor中預(yù)覽相應(yīng)的可交互文檔。根據(jù)前端的反饋，修改Swagger注解，并把新的文檔存儲(chǔ)到內(nèi)部Wiki或者API文檔庫（如果改動(dòng)量大的話，利用Diff工具提高效率）。

開發(fā)完成后啟動(dòng)Server，Swagger-UI的訪問地址為http://localhost:8080/swagger-ui.html

為了減少beta環(huán)境的沖突、加快部署速度，最好在本地開發(fā)環(huán)境聯(lián)調(diào)。

【5分鐘指南】Swagger2環(huán)境配置與使用

swagger: "2.0"
info:
  description: Click Link Below for Help
  version: v1
  title: demo13
  termsOfService: "http://www.github.com/kongchen/swagger-maven-plugin"
host: HOST
basePath: /s
tags:
  - name: Users
schemes:
  - http
paths:
  /users:
    post:
      tags:
        - Users
      summary: 創(chuàng)建用戶
      description: 根據(jù)User對(duì)象創(chuàng)建用戶
      operationId: postUser
      parameters:
        - in: body
          name: body
          required: false
          schema:
            $ref: "#/definitions/User"
      responses:
        "200":
          description: successful operation
          schema:
            type: string
  "/users/{id}":
    get:
      tags:
        - Users
      summary: 獲取用戶詳細(xì)信息
      description: 根據(jù)url的id來獲取用戶詳細(xì)信息
      operationId: getUser
      parameters:
        - name: "id"
          in: path
          required: true
          type: integer
          format: int64
      responses:
        "200":
          description: successful operation
          schema:
            $ref: "#/definitions/User"
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
      age:
        type: string

Swagger：Rest API的描述語言

RAML vs. Swagger vs. API Blueprint

Springfox Reference Documentation

Swagger使用

swagger-maven-plugin

通過Swagger進(jìn)行API設(shè)計(jì)，與Tony Tam的一次對(duì)話

API 設(shè)計(jì): RAML、Swagger、Blueprint三者的比較

API描述、發(fā)現(xiàn)與檔案入門

Spring Boot中使用Swagger2構(gòu)建強(qiáng)大的RESTful API文檔

API Design And Documentation

Swagger與其他API文檔編寫工具對(duì)比