インタラクティブAPIドキュメント
GitLab APIのインタラクティブドキュメントツールを紹介します。
OpenAPI仕様について
OpenAPI仕様（以前はSwaggerと呼ばれていました）は、RESTful APIへの言語にとらわれない標準的なインターフェースを定義しています。OpenAPI定義ファイルはYAMLフォーマットで書かれており、GitLabブラウザによって自動的に人間が読みやすいインターフェースにレンダリングされます。
GitLab APIの一般的な情報については、API Docsをご覧ください。
概要
インタラクティブAPIドキュメンテーションツールは、GitLab.comのウェブサイト上で直接APIをテストすることができます。利用可能なエンドポイントのうち、OpenAPI仕様で文書化されているのはごく一部ですが、現在のリストはツールの機能を示しています。
エンドポイントのパラメータ
エンドポイントの一覧を展開すると、説明、入力パラメータ（必要な場合）、サーバーの応答例が表示されます。一部のパラメータには、デフォルト値や許容値のリストが含まれています。
対話型セッションの開始
個人アクセストークン (PAT) は、対話型セッションを開始する方法の 1 つです。これを行うには、メインページで [作成者] を選択すると、現在の Web セッションで有効な PAT を入力するよう求めるダイアログボックスが表示されます。
エンドポイントをテストするには、まずエンドポイント定義ページで [試用] を選択します。必要に応じてパラメータを入力し、[Execute] を選択します。次の例では、version エンドポイントのリクエストを実行しました（パラメータは必要ありません）。ツールには、curl コマンドとリクエストの URL が表示され、その後に返されるサーバーのレスポンスが表示されます。関連するパラメータを編集して新しいレスポンスを作成し、もう一度Executeを選択します。
ビジョン
APIコードは唯一の真実の源であり、APIドキュメントはその実装と緊密に結合されるべきです。OpenAPI仕様は、APIを文書化するための標準化された包括的な方法を提供します。これは、GitLab REST APIを文書化するための最適なフォーマットとなるはずです。これにより、より正確で信頼性が高く、ユーザーフレンドリーなドキュメントが作成され、GitLab REST APIを使用する際の全体的なエクスペリエンスが向上します。
これを達成するためには、APIコードの変更ごとにOpenAPI仕様を更新することが必要です。そうすることで、ドキュメントは常に最新で正確なものとなり、ユーザーの混乱やエラーのリスクを減らすことができます。
OpenAPIドキュメンテーションはAPIコードから自動生成されるべきです。そうすることで、ドキュメント作成チームの時間と労力を節約することができます。
このビジョンの現在の進捗は、OpenAPI V2 epic の Document the REST API で追うことができます。