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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

如何減少部署時間另外行文

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

減少文檔的編寫時間

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

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

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

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

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

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

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

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

開發(fā)完成后啟動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對象創(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: 獲取用戶詳細信息
      description: 根據(jù)url的id來獲取用戶詳細信息
      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進行API設(shè)計，與Tony Tam的一次對話

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

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

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

API Design And Documentation

Swagger與其他API文檔編寫工具對比