关于 openapi-glossary
解释 OpenAPI 和 API 开发术语的参考词汇表，面向 API 团队及内容作者，帮助统一用词，涵盖描述文档、验证、文档和相关概念。
主要功能
- 01定义 API 与 OpenAPI 术语
- 02说明别名和用法区别
- 03涵盖验证与测试概念
- 04介绍文档和工具相关术语
适用场景
- 01统一 API 团队材料中的术语
- 02在教育内容中解释 OpenAPI 概念
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/openapi-glossary确认已加载。
详细介绍
OpenAPI 术语表
为避免在创建教育材料、工具和其他内容时产生混淆，使用共同的词汇至关重要。在 OpenAPI 社区中，很多人会用许多不同的说法来描述很多事情，因此我们来试着统一一下。
API
“应用程序编程接口”（Application Program Interface）这一通用定义可以指很多东西，接口类型也各不相同。OpenAPI 特指基于 HTTP 的 API，通常包括 REST、类 REST，以及许多通用类型的 RPC。
API-First
API 刚开始流行时，许多公司开始把它们当作营销噱头推出。这些 API 通常没什么实用价值，性能很少令人满意，使用起来也令人沮丧。
“API First” 是一种理念，认为团队应该优先构建 API，并让它们成为自己也愿意使用的产品，从而解决可用性、性能等问题，并有望为客户带来更好的体验。
API 描述
别称包括：“API 定义”或“API 契约”。
API 描述是关于 API 的元数据，用于说明有哪些端点、资源、HTTP 方法、标头、查询参数等。
描述采用特定的“API 描述格式”编写（例如：OpenAPI、JSON Schema、RAML、WSDL 等），通常保存在“API 描述文档”中（例如：openapi.yaml、schemas/payment.json），除非作者决定改用注解。
API 设计
专门使用 API 描述来规划 API，或使用能够生成／导出 API 描述的工具。在开始编码之前完成这项工作，称为 API 设计优先（API Design First）。从概念上看，这与 API First 不同，但两者并不互斥。
更多内容请参阅 API 设计优先与代码优先。
API 规范
过去，“API 规范”是众多用于描述大多数主要工具供应商所称的 API 描述文档的术语之一。它指的是用户编写用来描述_自己_ API 的文件。
问 100 个人，就会得到 100 种答案；但如今逐渐形成的共识是，API 规范是涵盖 API 开发中各种规范的总称，而这个总称之下还存在更具体的类别。
JSON-API、HAL、Siren 等消息格式都有各自的规范。 JSON、YAML 等数据格式都有各自的规范。 SPDY、HTTP/2、HTTP/3 等传输协议都有各自的规范。 OAuth 2、OpenID 等身份验证策略都有各自的规范。
API 规范的类型如此之多，为避免歧义，最好不要使用这个术语，而改用某个更具体的类别；或者，如果你说的是自己的 openapi.yaml，就称之为描述文档。
打包
别称包括：“外部引用内联”。
打包会从不同文件或 URL 中引入外部 $refs，并将它们放入 components 对象中。
这样做是为了生成单个 OpenAPI 文件，便于共享，尤其适用于不支持解析外部文件的工具。如果工具完全不支持 $ref，则需要采用打包之外的替代方案：解除引用。
回调
大多数编程语言都有回调的概念：将一个函数作为参数传递给另一个函数，并在后者执行完毕后运行。在 API 中也有完全相同的概念，可以传入一个 URL，以便在某项操作完成时收到通知。
这通常通过 Webhook 实现，因此 Webhook 比 Callabck 更常见，但 OpenAPI 专门使用 Callbacks 这一术语。
例如，API 提供了一个 POST /subscribe 操作，该操作要求在请求正文中提供一个回调 URL：
POST /subscribe
Host: my.example.com
Content-Type: application/json
{
"callbackUrl": "https://myserver.com/send/callback/here"
}
随后会向该 URL 发送一个 Webhook。
在 Swagger Docs: Callbacks 上了解更多关于 OpenAPI 回调的信息。
代码生成
契约测试
确认 API 是否如其所述接收和输出数据，可以通过多种方式进行。最常见的是，当你听到 OpenAPI 相关的契约测试时，人们通常指的是生产者契约测试。这意味着 API 开发团队（或附近的测试／QA 团队）编写了一套测试，用于获取 API 描述并与实际数据进行比较。
从概念上讲，契约测试与数据验证相同，只是在生命周期的不同阶段出于不同目的进行。底层可以使用相同的工具。
此外还有客户端契约测试：你可以在客户端测试套件中编写契约，然后调用 API，检查是否符合契约。
转换器
一组用于将 OpenAPI 描述转换为其他描述格式（例如 API Blueprint、HAR、RAML 等）的工具，反之亦然！有些工具还可以转换为 HTML，通常用于生成参考文档。
数据实例
数据验证
在存在多种验证类型时，通常简称为“验证”。数据验证基本上是取一些实际数据（可能是包含正文的完整 HTTP 消息，也可能仅是正文），并将其与 API 描述进行比较。
解引用
别称包括：“Dereferencing”“Internal Inlining”或“Transclusion”。
所有 $ref 都会被替换为其对应的值，就像复制粘贴一样。文件／对象表示中不再存在 $ref。如果有 10 个操作引用同一个模型 10 次，现在就会有 10 个不同的模型。
描述验证
别称包括：“Schema Validation”。
这与数据验证有很大不同。描述验证侧重于确保描述符合 OpenAPI Specification 本身。
当验证器不再局限于检查文档是否有效，而是开始检查自定义规则、设计理念、风格等内容时，使用的术语是“linting”。
可在 OpenAPI.Tools 上查看描述验证器列表。
文档
在 OpenAPI 领域，文档最常见的含义是参考文档，但优质的 API 文档远不止于此。指南、教程和其他类型的操作说明内容通常会与参考文档结合，以提供最佳的开发者体验。这种组合加上“注册以获取 API 令牌”之类的功能，通常称为开发者门户。
网关验证
在 API 网关中使用数据验证称为网关验证，它可以阻止无效请求浪费应用资源。AWS、Tyk、Express Gateway 等都支持一定程度的 OpenAPI 或 JSON Schema 网关验证。
链接
在计算和 API 的概念中，链接可以指很多东西；但在 OpenAPI 中，Link Object 表示响应的一种可能的设计时链接。
这有助于让 API 文档少一些 RPC 风格、多一些 REST 风格，为每个响应提示接下来可执行的操作。如果在运行时使用，则会更接近超媒体控件（又称 HATEOAS）：客户端收到响应后，可以结合标头和数据实例以及链接，判断接下来可执行的操作。
Linting
OpenAPI linter（例如 Spectral）可以确认 API 描述是否有效，也可以检查它们是否符合预先制定的规则，例如样式指南。大型公司的 API 治理团队可以制定样式指南，也可以共享指南，例如 openapi-contrib/style-guides 中的指南。
Mocking
一种模拟服务，它以描述文档为输入，然后将传入的 HTTP 请求路由到示例响应，或动态生成示例。
可在 OpenAPI.Tools 查看模拟服务列表。
OAS
这只是 OpenAPI Specification 的简称，它是定义各个版本 OpenAPI 应如何工作的互联网上的 Markdown 文件。
OpenAPI
别名包括“OpenAPI Specification”。
API 描述格式的新名称，由 API 规范定义。它以前称为 Swagger。
OpenAPI Initiative
OpenAPI Initiative（OAI）是负责 OpenAPI Specification（OAS）开发的组织。
Open API
开放 API 是公共 API。
提及 OpenAPI Specification、社区或 OpenAPI Initiative 时，“OpenAPI”中间不加空格。
参数
参数是一个统称，涵盖标头、路径参数、查询字符串参数；在 OpenAPI v2 中，它还包括请求正文（例如表单数据）。
详细了解 OpenAPI v3.0 规范中的参数。
参考文档
这与代码库、模块、包的“类、方法、常量”文档非常相似，用于说明各种输入和输出。参考文档是将 API 描述呈现为 HTML（或 PDF），方便技术背景稍弱的人了解如何使用 API。
引用
JSON Reference 可以指向其他位置的 JSON 结构。它可以指向当前文件中的对象，也可以引用其他文件，这些文件可能位于远程位置。引用位于 Reference Object 中，键为 $ref。以下是一些示例：
- Reference Object：
{"$ref": "https://example.com/api/openapi.yaml#/components/schemas/Pet"} - JSON Reference：
https://example.com/api/openapi.yaml#/components/schemas/Pet - JSON Pointer（指向被引用文件中的位置）：
/components/schemas/Pet
解析
查找 $ref 末尾所指向的值，但不会更改正在解析的文件或对象。
Schema
别名包括“Data Model”。
Schema 是一种元数据，用于描述数据类型及其其他属性，例如特定格式和验证规则。JSON Schema 是 Schema 的一个示例，但 OpenAPI 有自己版本的 JSON Schema，用于 schema 关键字可以出现的各种位置。
Schema 最常用于描述 HTTP 请求或响应的正文，但也可以描述各种参数，例如标头或路径参数。
SDK
“Software Development Kits”（软件开发工具包）是计算机领域的通用术语，但在 Web API 和 OpenAPI 的语境中，它通常指某种客户端库，供其他开发者在编程语言层面与 API 交互，而不是在 HTTP 库层面交互。
OpenAPI.Tools 上提供了 SDK 生成器列表。
服务端验证
利用数据验证的概念来
更多关于服务端验证的信息。
Swagger
从历史上看，“Swagger”是 OpenAPI Specification（OAS）的原始名称。它于 2011 年发布时名为 Swagger，SmartBear 收购 Swagger Specification 后曾沿用这一名称，并推出了一系列带有 Swagger 名称的工具，例如 Swagger Editor、Swagger Inspector、SwaggerHub 等。
2016 年，Swagger 规范交由 Open API Initiative 后，名称改为 OpenAPI。
如今，“Swagger”一词仅是 SwaggerHub 工具品牌的一部分。该规范名为“OpenAPI”（不是 OpenAPI/Swagger）。