跳到主要内容
版本:3.2.9.5

设计 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 规范编辑器,具有实时验证和模拟功能。