次の方法で共有

データ API ビルダーの OpenAPI

注

このセクションで説明する Data API Builder 2.0 の機能は現在プレビュー段階であり、一般公開前に変更される可能性があります。 詳細については、「 バージョン 2.0 の新機能」を参照してください。

OpenAPI 仕様は、HTTP API を文書化するための言語に依存しない標準です。 データ API ビルダーは、次の方法で OpenAPI をサポートします。

  • ランタイム構成で定義されているすべての REST 対応エンティティのメタデータの生成
  • そのメタデータを有効な OpenAPI スキーマにコンパイルする
  • ビジュアル UI (Swagger) を介して、またはシリアル化された JSON ファイルとしてスキーマを公開する
  • 特定のロールに対してアクセス可能な HTTP メソッドとフィールドのみを表示するようにスキーマをフィルター処理する

OpenAPI の説明ドキュメント

データ API ビルダーは、ランタイム構成と各 REST 対応エンティティのデータベース メタデータを使用して、OpenAPI 記述ドキュメントを生成します。

スキーマは 、OpenAPI.NET SDK を使用して構築され、 OpenAPI 仕様 v3.0.1 に準拠しています。 JSON ドキュメントとして出力されます。

OpenAPI ドキュメントには、次の場合にアクセスできます。

GET /{rest-path}/openapi

注

既定では、 rest-path は api。 この値は構成可能です。 詳細については、 REST 構成 を参照してください。

アクセス許可に対応した OpenAPI

DAB 2.0 以降、OpenAPI ドキュメントには、各エンティティに対して構成された実際のアクセス許可が反映されています。 生成されたスキーマでは、可能なすべての HTTP メソッドを文書化する代わりに、特定のロールがアクセスできるメソッドとフィールド のみが 表示されます。

アクセス許可を HTTP メソッドにマップする方法

DAB は、OpenAPI ドキュメントでエンティティのアクセス許可を HTTP メソッドの可視性に変換します。

権限操作 表示される HTTP メソッド
read GET
create POST
create + update PUT、PATCH
delete DELETE

たとえば、anonymous ロールにread エンティティに対するBookアクセス許可しかない場合、匿名ロールの OpenAPI ドキュメントには、GETの/api/Book操作のみが表示されます。 POST、PUT、PATCH、およびDELETEの操作は完全に省略されます。

フィールド レベルのフィルター処理

アクセス許可にフィールド レベルの include または exclude ルールが含まれている場合、OpenAPI スキーマにはそれらの制約が反映されます。 要求スキーマと応答スキーマには、ロールにアクセスできるフィールドのみが表示されます。 このフィルター処理によって、消費者は API が彼らの役割に応じて受け入れる内容や返す内容を正確に理解できます。

ロール固有の OpenAPI パス

DAB にはロール固有の OpenAPI エンドポイントが用意されているため、構成されているロールのスキーマを調べることができます。

GET /{rest-path}/openapi
GET /{rest-path}/openapi/anonymous
GET /{rest-path}/openapi/authenticated
GET /{rest-path}/openapi/admin

基本 /openapi パスは、既定の匿名ビューを返します。 各ロール固有のパスは、そのロールのアクセス許可にフィルター処理されたスキーマを返します。

Important

ロール固有の OpenAPI パス (/openapi/{role}) は、 開発モードでのみ使用できます。 運用モードでは、これらのエンドポイントは、ロールの列挙を防ぐために無効になります。 運用モードでは、基本 /openapi パスのみを使用できます。

注

ロール固有のエンドポイントは、ロールにランタイム構成内の任意の場所で構成されたエンティティのアクセス許可がない場合、 404 Not Found を返します。 少なくとも 1 つのエンティティに少なくとも 1 つの permissions エントリを持つロールのみが、OpenAPI ドキュメントを生成します。

例

次のアクセス許可の構成を検討してください。

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": { "include": ["id", "title", "year"] }
            }
          ]
        },
        {
          "role": "authenticated",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    }
  }
}

この構成では、次の操作を行います。

  • /api/openapi/anonymousには、応答フィールドGET /api/Book、id、およびtitleを含むyearのみが表示されます。
  • /api/openapi/authenticatedには、すべてのフィールドを含むGETに対するPOST、PUT、PATCH、DELETE、および/api/Book操作が表示されます。

Swagger UI

Swagger UI は、OpenAPI スキーマに基づく API の対話型の Web ベースのビューを提供します。

Development モードでは、データ API ビルダーは次の場合に Swagger UI を公開します。

GET /swagger

このエンドポイントは、ユーザー定義エンティティとの競合を回避するために、rest-path の下にネストされていません。

  • Last updated on