API文档先行还是API编码先行？
API文档先行是在编码之前先设计好API说明，Swagger提供Open API规范的文档范式，可通过IDE插件或Swagger网站提供的在线编辑工具编辑。
我们可在Idea开发工具下安装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();
我们直接编码接口代码，然后在接口方法上复制这两种模板，修改其中的一些数据即可。