API文件先行還是API編碼先行？

摘要： API文件先行是在編碼之前先設計好API說明，Swagger提供Open API規範的文件正規化，可通過IDE外掛或Swagger網站提供的線上編輯工具編輯。 我們可在Idea開發工具下安裝Swagger外掛 ，這樣可以實現語法自動提示。API規範主要由兩個部分組成：路徑編寫，如...

API文件先行是在編碼之前先設計好API說明，Swagger提供Open API規範的文件正規化，可通過IDE外掛或Swagger網站提供的線上編輯工具編輯。

我們可在Idea開發工具下安裝ofollow,noindex" target="_blank">Swagger外掛 ，這樣可以實現語法自動提示。API規範主要由兩個部分組成：路徑編寫，如果需要返回某個物件的JSON，那麼也可以定義這個物件的欄位型別：

paths:
/repository/deployments:
post:
tags:
- 流程釋出
summary: 釋出一個新流程
description: 獲得流程定義列表
operationId: file
consumes:
- application/x-www-form-urlencoded
produces:
- application/json
parameters:
- in: body
name: body
description: 把流程配置檔案vacationRequest2.bpmn20.xml釋出到流程中
required: true
schema:
$ref: '#/definitions/processConf'
responses:
200:
description: Indicates the deployment was created.
400:
description: Invalid status value

definitions:
processConf:
type: object
required:
- file
properties:
file:
type: string
example: vacationRequest2.bpmn20.xml

注意到兩個一級paths 和definitions ，paths 用來定義REST資源的URL，包括傳入傳出引數型別，傳入引數如果是一個物件型別，可以在schema中使用$ref 指向definitions 中的具體物件名稱，比如 $ref : '#/definitions/processConf'就是指向了definitions 下的processConf ，這個物件裡只有一個欄位file，型別是字串，內容是一個xml檔名稱。

當我們編寫好這個規範以後，可以通過https://app.swaggerhub.com/提供的工具轉換成Spring程式碼，它將上面的定義生成一個REST介面：

@Api(value = "repository", description = "the repository API")
public interface RepositoryApi {

@ApiOperation(value = "釋出一個新流程", nickname = "file", notes = "獲得流程定義列表o
@ApiResponses(value = { 
@ApiResponse(code = 200, message = "Indicates the deployment was created."),
@ApiResponse(code = 400, message = "Invalid status value") })
@RequestMapping(value = "/repository/deployments",
produces = { "application/json", "application/xml" }, 
consumes = { "application/x-www-form-urlencoded", "application/xml" },
method = RequestMethod.POST)
ResponseEntity<Void> file(@ApiParam(value = "把流程配置檔案vacationRequest2.bp
mn20.xml釋出到流程中" ,required=true )@Valid @RequestBody ProcessConf body);

這樣，我們開始實現這個介面，進行編碼，當然pom.xml中要有swagger依賴：

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
<scope>compile</scope>
</dependency>

當我們的程式碼通過Spring Boot執行以後，就可以在瀏覽器訪問http://localhost:8080/swagger-ui.html時自動出現下面：

API文件先行

前面演示的流程其實是API文件先行，先使用工具編制好API文件，然後生成程式碼說明模板，在這個模板上再進行詳細編碼，這樣做的好處能夠重點設計好API內容，不會被編碼細節打擾，壞處是，在詳細編碼中如果需要調整一些入參和出參，需要改文件，再該程式碼裡面的API文件，比較麻煩。如果使用自動生成，會覆蓋詳細編碼的工作。

API編碼先行

這是傳統直覺方式，把API文件看成是普通文件，寫好程式碼再寫文件，其實在REST前後端分離架構下，如果寫好API文件，前後端可以同時進行開發，而且提供前端人員對你的API測試的依據，對專案演進過程中如果程式碼有變動，而API文件沒有修改，導致功能都無法正常執行。

推薦辦法

為了避免API文件編制的繁瑣，也避免先編寫程式碼造成的低效率，推薦辦法是API文件和編碼同時進行，就在REST控制器介面方法上進行，這裡提供POST和GET兩個模板，只要複製貼上到自己的方法上，修改一些引數即可：

@ApiOperation(value = "建立一個新流程定義", nickname = "createProcessDef", notes =
"這是建立一個流程定義，會儲存到流程定義表中，同時BPMN的XML檔案生成上傳",
tags = {"流程定義",})
@ApiResponses(value = {
@ApiResponse(code = 201, message = "流程定義建立成功！")})
@RequestMapping(value = "/workflow",
produces = {"application/json"},
consumes = {"application/json"},
method = RequestMethod.POST)
ResponseEntity<Void> createProcessDef(@ApiParam(value = "建立流程定義") @Valid @RequestBody
ProcessDef body);

查詢模板：

@ApiOperation(value = "獲得流程定義列表", nickname = "repositoryProcessDefinitionsGet", notes =
"獲得流程定義列表", tags = {"流程定義",})
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Indicates the request was successful.", response =
ProcessDef.class, responseContainer = "List")})
@RequestMapping(value = "/workflow",
produces = {"application/json"},
method = RequestMethod.GET)
List<ProcessDef> repositoryProcessDefinitionsGet();

我們直接編碼介面程式碼，然後在介面方法上覆制這兩種模板，修改其中的一些資料即可。

#swagger#API

Spring Boot