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

创建OpenAPI规范时需要关注的10个关键要点，帮助您优化API设计。

什么是OpenAPI？

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

OpenAPI的起源与发展

OpenAPI的概念最初由Tony Tam在2010年开发Linux基金会赞助，创始成员包括IBM、谷歌、微软等知名公司。2016年，Swagger正式更名为OpenAPI规范（OAS）。目前，OpenAPI 3.0版本于2017年发布，3.1.0版本则于2021年发布。

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

以下是创建高质量OpenAPI规范时需要注意的10个关键要点，帮助您更好地描述和设计API。

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

API标题是OAS描述中的重要组成部分。一个好的标题应该简洁明了，能够快速传达API的核心功能。例如：

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

通过一个清晰的标题，开发者可以快速了解API的用途和上下文。

2. 编写全面的API说明

在标题之后，API说明为读者提供更深入的理解，帮助他们明确API的功能和作用。一个好的API说明应包括以下内容：

API的主要功能
支持的操作和资源

例如：

描述：书店电子商务API支持在线书店的购物体验，包括以下功能：

列出最近添加的书籍
创建和管理购物车
下订单并跟踪订单状态

3. 利用清晰有用的操作标识符

操作标识符（operationId）是OAS中的可选字段，用于唯一标识API中的操作。一个好的operationId应遵循以下原则：

避免泄露实现细节
使用功能性命名，例如：ListBooks

示例：

paths:
  /books:
    get:
      operationId: ListBooks

通过清晰的operationId，开发者可以更轻松地理解和引用API操作。

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

操作总结应以动词开头，简明扼要地描述操作的功能。例如：

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

5. 编写完整的操作说明

操作说明是将机器可读的细节转化为人类可读内容的关键部分。一个好的操作说明应包括以下内容：

操作的功能描述
支持的参数和默认行为
示例用例

示例：

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

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

在描述API时，应详细记录每个参数的名称、类型、默认值和用途。例如：

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. 验证一致性

在完成API设计后，检查所有路径、参数和模式定义是否符合命名标准，避免混用不同风格（如camelCase和under_score）。

10. 链接到外部文档

为API说明添加外部链接，帮助开发者快速找到相关资源，例如：

入门指南
详细的API使用文档

总结

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

在API上线前，建议进行开发者体验审查，确保API设计的可用性和一致性。如果您想了解更多关于API设计审查的技巧，可以参考相关文档和指南。

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