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