关于 REST API 的 OpenAPI 描述

关于 OpenAPI

OpenAPI 是用于描述 REST API 接口的规范。 它描述 API，而无需访问源代码或其他文档。 规范即可供人类读取，也可供机器读取。 有关详细信息，请参阅 OpenAPI 规范文档。

关于 GitHub 的 OpenAPI 描述

REST API 的 GitHub OpenAPI 描述已公开发布。 可以在开放源代码 github/rest-api-description 存储库中找到描述。

GitHub 同时提供 3.0 和 3.1 OpenAPI 描述。

对于每个描述，为每个产品：GitHub Free/GitHub Pro/GitHub Team (api.github.com)、GitHub Enterprise Cloud (ghec)，以及 GitHub Enterprise Server (ghes-X.X) 的每个版本。

对于每个产品，如果支持基于日期的版本控制，则会为每个基于日期的版本提供描述。 有关详细信息，请参阅 GitHub Free 文档中的 "API 版本"。

每个描述都以捆绑格式或取消引用格式提供。 捆绑格式用于 $ref 引用在端点之间共享的 OpenAPI 组件。 取消引用的格式包括完全扩展的描述。

使用 GitHub OpenAPI 描述

由于 OpenAPI 描述是计算机可读的，因此可以使用它来执行如下操作：

• 生成库以方便使用 REST API
• 验证并测试使用 REST API 的集成
• 使用第三方工具（如 Insomnia 或 Postman）探索 REST API 并与之交互。

例如，GitHub 使用 OpenAPI 描述生成 Octokit SDK。 GitHub 还使用 OpenAPI 描述为每个端点生成 REST API 参考文档。