跳至主要内容

关于 REST API 的 OpenAPI 描述

GitHub REST API 在符合 OpenAPI 规范的文档中进行了全面描述。

关于 OpenAPI

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

关于 GitHub 的 OpenAPI 描述

GitHub 的 REST API 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)。

对于每个产品,如果支持基于日期的版本控制,则每个基于日期的版本也都有一个描述。有关更多信息,请参阅“API 版本”。

每个描述都以捆绑或反引用格式提供。捆绑格式使用$ref引用端点之间共享的 OpenAPI 组件。反引用格式包含完全展开的描述。

使用 GitHub OpenAPI 描述

由于 OpenAPI 描述是机器可读的,因此您可以使用它来执行以下操作:

  • 生成库以方便使用 REST API
  • 验证和测试使用 REST API 的集成
  • 使用第三方工具(如 Insomnia 或 Postman)探索和交互 REST API

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