如何从代码生成OpenAPI规范 - BlazeMeter

你知道如何从代码中生成 OpenAPI 规范吗？本文将为你详细解答这一问题，并介绍相关方法和工具，帮助你更高效地管理 API 文档。

OpenAPI 规范的用途是什么？

RESTful API 的标准化格式，广泛用于 API 文档的生成、测试和维护。它不仅能帮助开发者清晰地定义 API 的结构和行为，还能通过自动化工具简化开发和测试流程，提高团队协作效率。

创建 OpenAPI 规范的两种方法

在理想的开发环境中，API 通常会在设计阶段就被精心规划并生成相应的规范。然而，现实往往与理想相去甚远。许多团队在开发 API 时缺乏规范化的流程，导致文档不完整甚至缺失。以下是两种常见的创建 OpenAPI 规范的方法：

手动创建 OpenAPI 规范

手动创建 OpenAPI 规范需要开发者或技术作家从头开始编写 API 定义。这种方式虽然灵活，但耗时且容易出错。以下是手动创建的主要问题：

工作量大：需要逐一分析 API 的结构和行为，并将其转换为 OpenAPI 定义。
维护困难：API 更新后，文档需要同步修改，否则很容易过时。
责任不明确：开发者可能不愿意承担额外的文档维护工作，而技术作家可能无法及时跟进代码的变化。

从代码生成 OpenAPI 规范

相比手动创建，从代码生成 OpenAPI 规范是一种更高效的方式。这种方法将代码视为 API 的唯一真实来源，通过工具链自动生成 OpenAPI 定义。以下是其主要优点：

减少重复工作：利用现有代码中的信息生成文档，避免手动编写。
实时更新：文档可以随着代码的变化而自动更新，保持一致性。
适应小团队：对于资源有限的小团队，这种方法可以显著提高效率。

在最近的 API 文档会议上，MongoDB 和 Adyen 等公司分享了他们的实践经验，表明这种方法不仅是一个折衷方案，甚至可能是某些团队的最佳选择。

从代码生成 OpenAPI 规范的工具和方法

根据我们的研究，OpenAPI 工具和库几乎支持所有主流编程语言。它们大致分为以下两类：

基于注释的工具

这类工具允许开发者在代码中通过注释或扩展直接定义 OpenAPI 规范。其特点是：

灵活性高：定义分布在代码库中，与实现紧密结合。
适用于遗留代码：对于已有代码库，可以通过添加注释的方式逐步生成规范。

例如，开发者可以在描述数据库实体（如用户、帖子或评论）的类中直接添加 JSON 模式模型。

基于框架的工具

这类工具依赖于特定的框架，能够自动生成大部分 OpenAPI 规范。其特点是：

自动化程度高：通过框架配置生成 API 路由及其文档。
减少开发者负担：开发者只需提供少量额外信息，如描述和注释。

例如，某些工具可以根据 API 路由的配置自动生成完整的规范，包括所有的输入和输出。

创建 OpenAPI 规范的工具

以下是一些支持不同编程语言的常用工具：

PHP

Swagger-PHP：通过注释生成 OpenAPI 规范。

Java

Springfox：为 Spring Boot 应用生成 OpenAPI 文档。
OpenAPI Generator：支持多种语言的代码和文档生成。

JavaScript/Node.js

Swagger-jsdoc：通过 JSDoc 注释生成 OpenAPI 定义。
Fastify：内置支持生成 OpenAPI 文档。

Python

Flask-RESTPlus：扩展 Flask 框架，支持 OpenAPI 文档生成。
FastAPI：原生支持 OpenAPI 规范。

Ruby

Grape：一个 RESTful API 框架，支持生成 OpenAPI 文档。

Go

go-swagger：支持生成和解析 OpenAPI 定义。
swag：通过注释生成 OpenAPI 文档。

ASP.NET

Swashbuckle：为 ASP.NET Core 应用生成 OpenAPI 文档。

如何从代码创建 OpenAPI 规范

一般工作流程

在实际生产环境中，从代码生成 OpenAPI 规范通常包括以下步骤：

选择工具：根据编程语言和框架选择合适的工具。
配置生成：通过注释或配置文件定义 API 的元数据。
生成文档：运行工具生成 OpenAPI 定义文件（如 YAML 或 JSON 格式）。
手动调整：对生成的文档进行必要的编辑和优化。
部署文档：将文档部署到开发者门户或其他平台。

此外，你可以将生成过程集成到持续集成（CI）环境中，例如使用 Jenkins 或 Travis 自动完成文档的生成和部署。

结论

OpenAPI 规范为 API 文档的创建和维护提供了强大的支持。无论是通过手动方式还是从代码生成，开发者都可以找到适合自己团队的工作流程。借助丰富的工具和库，几乎所有主流编程语言都能轻松集成 OpenAPI。通过合理利用这些工具，你的团队可以显著提升 API 文档的质量和开发效率。

编码愉快！

原文链接: https://www.blazemeter.com/blog/openapi-spec-from-code