设计 API

工程师总是强调在编码前设计计划的重要性。你需要根据业务需求明确 API 的功能目的，然后将业务语言转化为技术语言。通常，API 的设计围绕文档展开。

使用示例

在所有教程中，你将使用 Swagger Petstore 作为示例，指导你完成整个 API 生命周期的管理。

如何编写自己的 OpenAPI 规范

通过 JSON 或 YAML 格式的 OpenAPI 规范文件，可以定义遵循 API 设计最佳实践的 RESTful API。这可以确保可靠性、一致性和可扩展性。Swagger Editor 和 OpenAPI GUI 等开源工具可帮助创建、编辑和验证 OpenAPI 规范。许多集成开发环境和代码编辑器也有处理 OpenAPI 文件的插件。

你可以从示例中了解到 RESTful 架构风格的主要特点，包括：

• 资源的唯一标识：每个资源都有一个唯一的标识符，如 URL。
• 统一接口：使用标准化的 HTTP 方法和状态代码，如 GET、POST、PUT、DELETE 等。
• 无状态：API 不应存储客户状态信息。每个请求都应包含处理所需的全部信息，从而提高横向可扩展性。

有用的工具

以下是一些有助于编写 OpenAPI（原 Swagger）规范文档的实用工具：

• Swagger Editor：用于在线创建和测试 OpenAPI 规范的交互式编辑器。提供自动完成、实时验证和示例生成功能。
• Stoplight Studio：可视化建模工具，用于设计 API 和生成带有模拟数据的 OpenAPI 规范。
• OpenAPI Generator：根据 OpenAPI 规范自动生成客户端 SDK、服务器存根、文档等。支持多种语言。
• Postman：提供 OpenAPI 导入器和导出器，用于在集合和规范之间进行转换。还可自动生成代码。
• OpenAPI CLI：命令行工具，提供用于处理 OpenAPI 文件的完成、验证和其他实用程序。
• OpenAPI GUI：适用于 Windows 和 Mac 的桌面应用程序，为编辑 OpenAPI 文件提供用户界面，支持 YAML 和 JSON。
• REST United：OpenAPI 工具套件，包括模拟、文档、测试和代码生成。
• Apicurio：基于 Web 的 OpenAPI 规范编辑器，具有实时验证和模拟功能。