API的开发、测试与输出文档
前后端分离和微服务理念的盛行，导致API成为了一种重要的交付物。但是，如果没有把API有效管理起来的机制，API的复用就难以保障，这样独立出API层的价值就会大打折扣。本文以
OpenAPI Sepecification为基础，结合Swagger和JMeter等工具的使用，演示一个完整的API开发和管理过程。
演示项目地址：https://github.com/jasony62/try-swagger.git
基本概念
完整的API管理应该包括几个方面：设计、开发、测试、文档、使用等方面。围绕OpenAPI Specification(OAS)已经有了丰富的生态，覆盖了上述各个方面，在示例项目中，用到了swagger-jsdoc生成定义文档；用swagger-ui和swagger-editor查看或编辑文档（在线版）；openapi-generator-cli生成JMeter测试计划；JMeter执行冒烟测试；openapi-generator-cli生成Markdown格式文档（离线版）。
Swagger提供一套围绕API开发全生命周期的工具，它是API定义事实上的标准。我理解，其基本思路是文档优先于代码，也就是先按规范写好文档，然后通过文档生成代码框架，包括了：swagger-editor，swagger-ui，swagger-codegen等一系列工具。
目前，OpenAPI Specification(OAS)是通用标准，当前版本是3.0。Swagger有自己的API定义规范，当前的版本是2.0。这两个规范并不相同，但是可以通过swagger-editor进行转换。前面提到各种工具就是围绕API定义规范提供了各种功能。
本文的重点是介绍如何利用各种工具实现API开发的流程，OAS的具体使用可以查看规范，这里只需要知道，OAS支持json和yaml两种格式编写，实例中都是用yaml。
设计和开发
虽然Swagger提供了强大的代码生成能力，可以先设计再自动生成代码框架，但是这可能更适合从0开始的项目，特别是在使用自有后端框架的情况下，例如：本示例采用了tms-koa，需要的是代码和设计同步完成（甚至是后补设计）。
在tms-koa框架中使用swagger-jsdoc实现了从代码中收集API定义，自动生成在线文档的服务。
/**
* @swagger
*
* /tryGet:
* get:
* tags:
* - test1
* description: 测试get方法，传入参数，并返回结果
* parameters:
* - name: value
* description: 传入1个值
* in: query
* required: false
* schema:
* type: string
* responses:
* '200':
* description: 将输入的值作为执行结果返回
* content:
* application/json:
* schema:
* "$ref": "#/components/schemas/ResponseData"
*/
tryGet() {
let { value } = this.request.query
const { bucket } = this
console.log('tryGet', value)
return new ResultData(`收到：${value}`)
}
上面的代码片段实现了名称为tryGet的API，在方法注释中用@swagger表明这是一个用OAS设计的API。启动服务，访问定义的在线文档地址。
curl -v "http://localhost:3000/oas?refresh=Y"
{"openapi":"3.0.0","info":{"title":"Try Swagger","version":"1.0.0"},"paths":{"/tryGet":{"get":{"tags":["test1"],"description":"测试get方法，传入参数，并返回结果","parameters":[{"name":"value","description":"传入1个值","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"将输入的值作为执行结果返回","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseData"}}}}}}},"/tryPost":{"post":{"tags":["test2"],"description":"测试post方法，传入参数，并返回结果","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"将输入的值作为执行结果返回","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseData"}}}}}}}},"components":{"schemas":{"ResponseData":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"result":{"type":"object"}}}}},"tags":[{"name":"test1","description":"测试1"},{"name":"test2","description":"测试2"}]}
可以看到，tms-koa已经完成了在线文档的生成工作（json格式）。通过在url中添加refresh参数，可以实时更新在代码中的修改（考虑到性能问题，如果不指定这个参数，在线文档只生成一次）。还可以通过swagger-ui用更直观的方式查看文档。
docker-compose up swagger-ui
用swagger-ui查看在线文档
通常写完API需要通过调用看看代码执行情况，swagger-ui中点Try it out就可以通过界面输入参数进行调用。
有时我们可能需要看看生成定义是否正确，也可能需要进行修改，这时可以使用swagger-editor。
docker-compose up swagger-editor
在swagger-editor中指定在线文档地址
在swagger中查看在线文档
swagger-editor中内置了编辑API定义的功能，这样能减少手工工作。但是，现在还没有将编辑结果返回到代码中的方法，只能收工拷贝。
通过上面的方法，我们已经可以实现API定义的可视化和实时更新。通过提供线上文档，可以更方便的进行信息共享，促进API的复用。
测试
API开发完成后通常要进行持续迭代，特别是不同API依赖的公共逻辑发生变化时，通常需要进行回归测试。前面提到基于API定义可以自动生成代码，那么是否也可以生成自动测试代码呢？通过openapi-generator-cli可以根据指定的API定义生成JMeter的测试计划，这样就可以实现简单的冒烟测试了。
执行演示项目中的命令
/bin/sh gen-testplan.sh
执行后，会在项目目录下生成jmeter目录，其中包含了自动生成的测试计划。
自动生成的测试计划
只生成测试计划还不够，手工执行仍然是个工作量，是否可以自动执行测试计划？JMeter支持命令行执行方式，因为可以通过写脚本通过命令行自动执行测试计划。
执行演示项目中的命令
/bin/sh run-testplan.sh
执行后，会在jmeter目录下生成report目录，其中包含了测试报告。
自动生成测试报告
通过上面的步骤就可以实现简单的自动化回归测试了。
离线文档
有时候只提供在线文档是不够的，还需提供离线文档。openapi-generator-cli不仅可以生成JMeter测试代码，也可以生成Markdown格式的文档。
执行演示项目中的命令
/bin/sh gen-markdown.sh
自动生成文档
后记
基于OAS标准规范，通过上面几个环节初步实现了API的完整开发过程，既可以提高效率也可以提高质量。但是在实践过程中还会有大量的细节问题需要解决，例如：如何实现多个API定义的内容的共享（通过back/config/swagger.js指定共享定义）？如何定制自动生成的测试计划（查看run-testplan.sh中测试计划变量的部分）？
做好API开发是个系统性的工作，需要持续学习多方面的知识并实践，但是这应该作为当前后端程序员的基础技能之一。
