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