OpenAPI の記述について
OpenAPI は、REST API を記述するための標準仕様です。 OpenAPI の記述は、人間にとっても機械にとっても判読しやすくなっており、 あらかじめドキュメントを読んだり実装を理解したりする必要がありません。 GitHub は、REST API を OpenAPI 3.0 準拠のドキュメントとして公開しています。
GitHub OpenAPI の記述を取得する
OpenAPI の記述は、オープンソースの REST API OpenAPI Description リポジトリにあります。
OpenAPI の記述には 2 つの形式があります。 バンドルバージョンは、再利用と判読に適した OpenAPI コンポーネントを含んでいるため、たいていの場合に有効です。 完全逆参照バージョンは、ツール環境でコンポーネントへのインライン参照がサポートされていない場合のために用意されています。
GitHub OpenAPI 記述を使用する
OpenAPI の記述にはいろいろな使い方があります。 たとえば、次のような方法を使用します。
- 独自の API クライアントを生成する。
- GitHub REST API の記述を検証してテストする。
- Insomnia や Postman といったサードパーティツールを使用して、GitHub Enterprise Server REST API を調べ、操作する。
たとえば、GitHub は REST OpenAPI の記述を使用して GitHub Enterprise Server REST API リファレンスドキュメントを生成します。