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

注意到两个一级pathsdefinitionspaths用来定义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和SpringFox文档化Spring Boot REST API

#swagger   #API     

Spring Boot

猜你喜欢