前台和后台的分离以及微服务概念的流行，使得API成为一个重要的交付品。 但是，如果没有有效管理API的机制，API的重用性将难以保证，独立API层的价值也将大打折扣。 本文基于OpenAPI规范，通过使用Swagger和JMeter等工具，展示了一个完整的API开发和管理过程。 示范项目地址:jasony62/try-swagger.git基本概念完整的API管理应该包括几个方面:设计、开发、测试、文档、使用等。 OpenAPI规范(OAS)有着丰富的生态，涵盖了以上几个方面。在示例项目中，swagger-jsdoc用于生成定义文档；使用swagger-ui和swagger-editor查看或编辑文档(在线版本);Open-generator-CLI生成JMeter测试计划；JMeter执行烟雾测试；Open-generator-CLI生成Markdown格式文档(离线版本) Swagger提供了一套围绕API开发全生命周期的工具，是API定义事实上的标准。 我理解的基本思路是文档优先于代码，即先按照规范写文档，然后通过文档生成代码框架，包括swagger-editor、swagger-ui、swagger-codegen等一系列工具。 目前OpenAPI规范(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 * */try get:* get:*标记:*-test1 *描述:测试get方法，传入参数，返回结果*参数:*-name: value *描述:1 value * in:query * required:false * Schema:* type:string * responses:* ' 200 ':*描述:返回输入值作为执行结果* content:* application/JSON:* Schema:" $ ref ":" #/components/schemas/response data " */try get(){ let { value } = this . query const value)返回新的结果数据(` received: ${value}`)}上面的代码片段实现了名为tryget的API，在方法注释中用@swagger表示为用OAS设计的API。 启动服务并访问定义的在线文档地址。 curl-v " http://localhost:3000/OAS？Refresh = y "{"open API ":"3.0.0 "，" info ":{"title ":"tryswagger "，" version ":"1.0.0 "}，" paths ":{"/tryget ":{并返回结果"，"参数":[{"name ":"value "，" description ":"1 value传入"，" in ":"query "，" required ":false，" schema ":{"type ":"string "}]，" Responses ":{ " 200 ":{ " description ":"返回 " responses ":{ " 200 ":{ " description ":"返回输入的值作为执行结果"，" content ":{ " application/JSON ":{ " $ ref ":" #/components/schemas/response data " } } } } } }，" components ":{ " schemas ":{ " response data ":{ " type ":" object "，" properties ":{ " code ":{ " type ":" integer " }，" msg": {"type": "string"}，" result ":{ " result " 通过在url中添加refresh参数，可以实时更新代码中的更改(考虑到性能问题，如果不指定该参数，在线文档将只生成一次) 您还可以通过swagger-ui以更直观的方式查看文档。 Docker-compose up swagger-ui用swagger-ui查看在线文档通常在编写完API后，需要调用来查看代码执行情况。在swagger里试试吧——ui可以通过界面输入参数来调用。 有时我们可能需要查看生成的定义是否正确，或者我们可能需要修改它，所以我们可以使用swagger-editor。 Docker-compose up swagger-editor在swagger-editor中指定在线文档地址，在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目录中生成报告目录，其中包含测试报告。 测试报告的自动生成可以通过以上步骤实现简单的自动回归测试。 离线文档有时仅提供在线文档是不够的，还需要提供离线文档。 Open-generator-CLI不仅可以生成JMeter测试代码，还可以生成Markdown格式的文档。 在演示项目中执行命令/bin/sh gen-markdown.sh，自动生成文档的postscript。基于OAS标准规范，通过以上步骤初步实现了API的完整开发过程，提高了效率和质量。 但是在实际操作中会有很多细节需要处理，比如:如何共享多个API定义的内容(通过back/config/swagger.js指定共享的定义)？如何自定义自动生成的测试计划(查看run-testplan.sh中的测试计划变量部分)？做好API开发是一个系统的工作，需要多方面的不断学习和实践，但应该是当前后台程序员的基本功之一。 见开放API规范jmeter CLI模式just B4/docker-jmeter https://swagger . io。