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 リファレンス ドキュメントも生成されます。