​
概要

APIプレイグラウンドは、ユーザーがAPIエンドポイントをテスト・探索できるインタラクティブな環境です。開発者はAPIリクエストを作成して送信し、ドキュメントから離れることなくレスポンスを確認できます。
“trigger an update” エンドポイント向けのAPIプレイグラウンド。
このプレイグラウンドは、OpenAPI仕様またはAsyncAPIスキーマから自動生成されるため、APIの更新内容は自動的にプレイグラウンドに反映されます。docs.jsonでベースURLと認証方法を定義したうえで、手動でAPIリファレンスページを作成することも可能です。 APIプレイグラウンドはOpenAPI仕様からの生成を推奨します。OpenAPIドキュメントの作成については、OpenAPI Setupを参照してください。

​
はじめに

1

OpenAPI 仕様ファイルを追加する

Swagger Editor または Mint CLI を使って、OpenAPI 仕様ファイルが正しい形式か検証してください。
/your-project
  |- docs.json
  |- openapi.json
2

`docs.json` を設定する

docs.json を更新して OpenAPI 仕様を参照します。ナビゲーション要素に openapi プロパティを追加すると、OpenAPI ドキュメントで定義された各エンドポイントのページが自動生成されます。次の例では、openapi.json で定義された各エンドポイントのページを生成し、ナビゲーションの「API reference」グループ配下に整理します。
"navigation": {
  "groups": [
    {
      "group": "API reference",
      "openapi": "openapi.json"
    }
  ]
}
特定のエンドポイントだけページを生成したい場合は、ナビゲーション要素の pages プロパティにエンドポイントを列挙します。次の例では、GET /users と POST /users のページのみを生成します。ほかのエンドポイントも生成するには、pages 配列に追加してください。
"navigation": {
  "groups": [
      {
        "group": "API reference",
        "openapi": "openapi.json",
        "pages": [
          "GET /users",
          "POST /users"
        ]
      }
  ]
}

​
プレイグラウンドのカスタマイズ

docs.json で以下のプロパティを定義すると、APIプレイグラウンドをカスタマイズできます。
​
playground
object
APIプレイグラウンドの設定。
​
examples
object
自動生成されるAPIサンプルの設定。

​
設定例

{
 "api": {
   "playground": {
     "display": "interactive"
   },
   "examples": {
     "languages": ["curl", "python", "javascript"],
     "defaults": "required"
   }
 }
}
この例では、APIプレイグラウンドをインタラクティブにし、cURL、Python、JavaScript のサンプルコードスニペットを表示するように構成しています。コードスニペットには、必須パラメータのみが表示されます。

​
カスタムエンドポイントページ

APIドキュメントをより細かく制御したい場合は、OpenAPI仕様の x-mint 拡張を使うか、各エンドポイント用に個別の MDX ページを作成してください。 どちらの方法でも次のことが可能です:
  • ページのメタデータをカスタマイズ
  • 例などの追加コンテンツを追加
  • ページごとにAPIプレイグラウンドの挙動を制御
すべてのAPIドキュメントをOpenAPI仕様から自動生成し、1つのファイルで一元管理できるため、x-mint 拡張の利用を推奨します。 個別の MDX ページは、小規模なAPIやページ単位で変更を試したい場合に適しています。 詳細は、x-mint extension と MDX Setup を参照してください。

​
参考情報

  • WebSocket のリファレンスページを生成するための AsyncAPI スキーマの作成については、AsyncAPI Setupをご覧ください。