此页面定义了理解 OpenAPI 重要的概念，以及如果您想参与规范讨论可能会遇到的术语和缩略语。

缩略语

这些缩略语通常用于 OpenAPI 讨论，并在以下部分定义。

  • BGB: 业务治理委员会
  • OAD: OpenAPI 描述
  • OAI: OpenAPI 倡议
  • OAS: OpenAPI 规范
  • SIG: 特别兴趣小组
  • TDC: 技术开发社区
  • TSC: 技术指导委员会
  • TOB: 技术监督委员会

定义

  • 业务治理委员会 (BGB): 代表 OAI 成员的团体，负责倡议预算、商标以及可能的未来认证计划，如 OAI 章程 中所述
  • 文档: 本地文件、网络资源或其他具有特定格式的独立实体，例如 JSON 或 YAML
    • 入口文档: OAD 中处理开始的文档，从 OpenAPI 对象开始 (3.0, 3.1)
    • 引用文档: OAD 中不是入口文档的文档
  • 学习网站: 本网站，learn.openapis.org (仓库)
  • 月球漫步: OAS 下一个（3.x 之后）主要版本的代号和 SIG (公告, 仓库)
  • OpenAPI 描述 (OAD): 一个或多个根据 OpenAPI 规范的特定版本编写的文档，共同描述了一个 API
  • OpenAPI 倡议 (OAI): 负责开发 OpenAPI 规范的组织（不要与无关且较新的“OpenAI”混淆），网站
  • OpenAPI 规范 (OAS): OpenAPI 格式的形式要求，存在多个版本（例如，3.0.3、3.1.0）(仓库)
  • 外联委员会: 一组致力于扩大 OAS 影响力的志愿者 (仓库)
  • 覆盖规范: overlays SIG 提出的规范 (仓库)
  • 特别兴趣小组 (SIG): 专注于 特定主题 的 OpenAPI 工作组，这些主题与 OAS 或可能的其他配套规范相关
  • 技术开发社区 (TDC): 一群在 OpenAPI 项目上工作并提供反馈的开发人员和规范编写者 (每周 Zoom 通话 在美国太平洋时间周四上午 9 点至 10 点举行)
  • 技术指导委员会 (TSC): 一群人 负责管理 OAI 的规范工作，如 OAI 章程 中所述
  • 工作流程规范: workflows SIG 提出的规范 (仓库)

文档和 OpenAPI 描述

OpenAPI 描述或 OAD 可以结构化为一个或多个文档，通过引用连接。这些文档通常存储为具有 .json 或 .yaml（或 .yml）扩展名的本地文件，或作为类型为 application/openapi+json 或 application/openapi+yaml 的 HTTP 可访问网络资源。

关于“文档”、“定义”和“描述”历史的说明

直到 OAS 3.0.3 和 3.1.0，OAS 包含一个名为“OpenAPI 文档”的部分，其定义根据 OAS 版本而有所不同。术语“OpenAPI 定义”、“OpenAPI 描述”以及其他变体和组合也在规范或 learn.openapips.org 网站中使用。

2023 年 9 月，OAI 技术指导委员会 (TSC) 同意将“OpenAPI 描述”标准化为描述 API 的完整逻辑实体，并将术语“文档”（小写）保留为其常用含义。解决“OpenAPI 描述”和“OpenAPI 定义”之间的争论取决于这样的观察：虽然在从 OAD 生成 API 代码时“定义”是合适的，但当为现有 API 编写 OAD 时，它是不准确的。术语“描述”在这两种情况下都是准确的。