关于 REST API 的 OpenAPI 描述

关于 OpenAPI

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

关于GitHub的 OpenAPI 描述

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

GitHub 提供 3.0 和 3.1 OpenAPI 说明。

对于每个说明，每个产品都有一个版本：GitHub Free/GitHub Pro/GitHub Team（）、 api.github.com （GitHub Enterprise Cloudghec）和每个版本的GitHub Enterprise Server（）。ghes-X.X

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

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

使用 GitHub OpenAPI 描述

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

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

例如， GitHub 使用 OpenAPI 说明生成 Octokit SDK。 GitHub 还使用 OpenAPI 说明为每个终结点生成 REST API 参考文档。