インタラクティブAPIドキュメント

OpenAPI仕様は、RESTful APIに対して、言語に依存しない標準的なインターフェースを定義します。OpenAPI定義ファイルはYAML形式で記述されており、GitLabブラウザによって、人間が判読しやすいインターフェースに自動的にレンダリングされます。

GitLab APIの一般的な情報については、GitLabを使用して拡張するを参照してください。

インタラクティブAPIドキュメントツールを使用すると、GitLab.comのWebサイトでAPIテストを直接実行できます。OpenAPI仕様でドキュメント化されているのは、使用可能なエンドポイントのほんの一部ですが、現在のリストはツールの機能を示しています。

エンドポイントパラメータ

エンドポイントリストを展開すると、説明、インプットパラメータ（必要な場合）、サーバーの応答例が表示されます。一部のパラメータには、デフォルト値、または許可される値のリストが含まれています。

インタラクティブセッションを開始する

パーソナルアクセストークン（PAT）は、インタラクティブセッションを開始する方法の1つです。インタラクティブセッションを開始するには、メインページから許可するを選択します。そうすると、ダイアログボックスが表示され、現在のWebセッションで有効なPATを入力するよう求められます。

エンドポイントをテストするには、まずエンドポイント定義ページでTry it out（試用）を選択します。必要に応じてパラメータを入力し、Execute（実行）を選択します。次の例では、versionエンドポイントのリクエストを実行しました（パラメータは不要）。ツールには、curlコマンドとリクエストのURLに続いて、返されたサーバーの応答が表示されます。関連するパラメータを編集して、もう一度Execute（実行）を選択すると、新しい応答を作成することができます。

ビジョン

APIコードは信頼できる唯一の情報源であり、APIドキュメントは、その実装に緊密に結び付けられている必要があります。OpenAPI仕様は、APIをドキュメント化するための標準化された包括的な方法を提供します。これは、GitLab REST APIをドキュメント化するための最適な形式である必要があります。これにより、より正確で信頼性が高く、ユーザーフレンドリーなドキュメントが実現し、GitLab REST APIを使用する際の全体的なエクスペリエンスが向上します。

それを実現するには、APIコードに変更があるたびにOpenAPI仕様を更新する必要があります。そのように更新することで、ドキュメントが常に最新で正確なものとなり、ユーザーの混乱やエラーのリスクを軽減することができます。

OpenAPIドキュメントをAPIコードから自動生成して、簡単に最新かつ正確な状態に保てるようにする必要があります。その結果、ドキュメントチームの時間と労力を節約できるようになります。

OpenAPI V2仕様によるREST APIのドキュメント化に関するエピックで、このビジョンの現在の進捗状況を追跡できます。