REST API の OpenAPI の記述について

GitHub REST API は、OpenAPI に準拠したドキュメントで完全に説明されています。

この記事で

OpenAPI について

OpenAPI は、REST API インターフェイスを記述するための仕様です。 ソース コードや追加のドキュメントへのアクセスを必要とせずに API について記述します。 仕様は人間とマシンの両方で読み取り可能です。 詳しくは、OpenAPI 仕様のドキュメントをご覧ください。

GitHubの OpenAPI の説明について

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