Skip to main content

关于 REST API 的 OpenAPI 描述

OpenAPI 3.0 符合性文档中全面描述了 GitHub REST API。

关于 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 参考文档。