REST API の OpenAPI の記述について

GitHub Enterprise Cloud の 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 のバージョン」を参照してください。

各説明は、バンドル形式または逆参照形式で使用できます。 バンドルされた形式は、エンドポイント間で共有される OpenAPI コンポーネントを参照するために $ref を使用します。 逆参照形式には、完全に展開された説明が含まれます。

GitHub OpenAPI 記述を使用する

OpenAPI の説明はマシンで読み取り可能であるため、これを使用して次のような操作を行うことができます。

  • REST API の使用を容易にするライブラリを生成する
  • REST API を使用する統合を検証してテストする
  • Insomnia や Postman といったサードパーティツールを使用して、REST API を調べ、操作する

たとえば、GitHub では、OpenAPI の記述を使用して Octokit SDK が生成されます。 GitHub では、OpenAPI の記述を使用して、各エンドポイントの REST API リファレンス ドキュメントも生成されます。