OpenAPI 规范创建指南｜优化 API 设计的 10 个关键要点

创建 OpenAPI 规范可以为 API 设计带来一致性和标准化，使开发者能够轻松定义和分享 API。本文将详细介绍 OpenAPI 的基本概念，以及在创建规范时需要关注的 10 个关键要点，帮助您优化 API 设计。

一. 什么是 OpenAPI？

OpenAPI 是一种用于 HTTP API 的规范语言，旨在通过定义结构和语法为 API 带来一致性和标准化，而不依赖于特定编程语言。

OpenAPI 的起源与发展

2010 年，Tony Tam 在开发 Swagger 时提出概念。
随后纳入 OpenAPI 倡议，由 Linux 基金会赞助，创始成员包括 IBM、谷歌、微软等。
2016 年，Swagger 更名为 OpenAPI 规范（OAS）。
2017 年发布 3.0 版本，2021 年发布 3.1.0 版本。

二. 创建 OpenAPI 规范的 10 个关键要点

以下 10 个关键要点有助于创建高质量、可维护的 OpenAPI 规范：

1. 编写清晰简洁的 API 标题

API 标题应简洁明了，快速传达核心功能：

不佳示例：一些服务名称
优秀示例：书店库存管理

2. 编写全面的 API 说明

说明应描述 API 的主要功能和支持的操作：

书店电子商务 API 支持在线书店购物体验：
- 列出最近添加的书籍
- 创建和管理购物车
- 下订单并跟踪订单状态

3. 利用清晰的操作标识符（operationId）

用于唯一标识 API 操作：

paths:
  /books:
    get:
      operationId: ListBooks

原则：避免泄露实现细节，使用功能性命名。

4. 撰写简洁完整的操作总结

总结应以动词开头，简明描述操作功能：

不佳示例：买书
优秀示例：列出书店中可供浏览的书籍，并支持筛选以缩小结果范围

5. 编写完整的操作说明

描述功能、参数和默认行为，并提供示例用例：

paths:
  /books:
    get:
      operationId: ListBooks
      summary: 列出书店中可供浏览的书籍
      description: 根据搜索条件提供分页书籍列表；未提供搜索条件时按字母顺序返回。
      parameters:
        - in: query
          name: q
          type: string
          description: 按标题或描述筛选书籍

6. 记录所有查询参数与模式对象

详细记录参数名称、类型、默认值和用途：

parameters:
  - in: query
    name: q
    type: string
    description: 用于按标题和描述过滤书籍
  - in: query
    name: limit
    type: integer
    default: 25
    description: 每次返回的记录数，默认为 25

7. 捕获所有操作的成功与错误响应代码

帮助开发者快速理解可能的响应：

responses:
  "200":
    description: 请求成功
  "401":
    description: 无效的 API 凭据
  "403":
    description: 无权访问资源

8. 定义统一的错误响应模式

简化客户端错误解析：

responses:
  "401":
    description: 无效的 API 凭据
    content:
      application/problem+json:
        schema:
          $ref: "https://opensource.zalando.com/problem/schema.yaml#/Problem"

9. 验证一致性

检查路径、参数和模式命名是否一致，避免混用 camelCase 和 under_score。

10. 链接到外部文档

提供快速访问相关资源的入口，例如：

入门指南
详细 API 文档

三. 总结

高质量 API 设计不仅关注 CRUD 模式和有效负载结构，还需保证描述清晰、一致。通过遵循上述 10 个关键要点，您可以创建易于理解和使用的 OpenAPI 规范，从而显著提升开发者体验（DX）。

上线前，建议进行开发者体验审查，确保 API 可用性和一致性。

原文链接: https://tyk.io/blog/10-essentials-when-creating-an-open-api-specification/