JSONからOpenAPIレスポンススキーマを生成

JSONサンプルからレスポンススキーマを推定し、OpenAPI 3.0.3のYAMLパスを1つ生成します。

レスポンスサンプルとエンドポイント

JSONレスポンスサンプル

固定エンドポイントパス

HTTPメソッド

生成されたOpenAPI YAML

openapi: 3.0.3
info:
  title: Generated API
  version: 1.0.0
paths:
  "/api/users":
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  schemas:
    Response:
      type: object
      required:
        - "id"
        - "name"
      properties:
        "id":
          type: integer
        "name":
          type: string

仕組み

JSONレスポンスのサンプルを貼り付け、固定パスを入力し、GET、POST、PUT、DELETEから選びます。生成器はレスポンス本文のスキーマを推定し、OpenAPI 3.0.3 YAML文書に配置します。

レスポンスに含まれる変化を示す代表的なサンプルを使います。同じ配列位置に複数のオブジェクトがある場合、生成器はプロパティを統合し、観測されたすべてのオブジェクトにある場合だけ必須にします。

YAMLを使う前に、推定された型と必須フィールドを確認してください。リクエスト本文、パラメーター、認証、エラーレスポンス、パスパラメーターの宣言は自分で追加します。その後、完成した文書をOpenAPIバリデーターで確認してください。

JSONの例はあるもののレスポンススキーマがない場合に使います。入力されたサンプルをもとに、選択したパスとメソッドだけを記述します。

手順

JSONレスポンスのサンプルを貼り付ける
固定パスを入力してメソッドを選ぶ
レスポンススキーマを確認してコピーする

具体例

GET /api/usersでは、{"user":{"id":7,"name":"Ada"},"tags":["vip",null,7],"metrics":[{"count":2,"score":1.5},{"count":3,"active":true}]}を貼り付けます。このサンプルには、入れ子のオブジェクト、複数の型を含む配列、2つの指標オブジェクトがあります。

出力ではuser、tags、metricsが必須になります。両方の指標オブジェクトにcountがあるため、そこでも必須です。scoreとactiveはそれぞれ1つのオブジェクトにしかないため任意です。tagsは文字列または整数を受け入れます。サンプルにnullもあるため、観測された両方の型はnullableです。

利用する場面

パスを文書化する際に、JSONレスポンス本文の例から初期のOpenAPIレスポンススキーマを作るために使います。

観測されたレスポンス構造の整理に役立ちます。生成文書には、APIのリクエスト、セキュリティ、エラー、パラメーターの詳細が別途必要です。

よくある間違い

オブジェクトが1つだけの場合、含まれるすべてのプロパティが必須に見えます。レスポンスごとに異なるプロパティを確認するには、同じ配列位置に複数の代表的なオブジェクトを用意してください。

推定結果を完全なAPI定義とみなさないでください。nullの扱い、任意フィールド、配列の型違い、固定パスを確認し、対象外のリクエストやエラーの詳細を追加してください。

推定ルール

各オブジェクト位置で、必須キー = 観測されたすべてのオブジェクトにあるキー。

各値で、推定スキーマ = 観測された非null型の集合。

既知の型とnullが観測された場合、その型付きスキーマをnullableにします。

これはサンプルからの推定であり、実行時の契約検証ではありません。1つの例だけでは、本番レスポンスで省略されるフィールドを判断できません。

制限と前提

結果はサンプルで観測された値を記述します。すべての例にないフィールドを特定したり、本番で省略可能と証明したり、空の配列の要素型を推定したりできません。nullだけの値は型を推定できません。複数の型は候補として表されるため、API契約と照合が必要な場合があります。

用語

OpenAPI文書: OpenAPI文書はAPIのパス、操作、入力、レスポンスなどを機械可読形式で記述します。
スキーマ: スキーマは、名前付きプロパティを持つオブジェクトなど、データの想定構造と値の型を記述します。
必須プロパティ: この出力で必須とは、その位置で観測されたすべてのオブジェクトにプロパティがあったことを意味します。本番の動作を証明するものではありません。

よくある質問

サンプルからどのようにレスポンススキーマを作りますか？

生成器はJSONサンプルのすべての値を調べます。オブジェクトのプロパティを作り、配列のすべての要素を確認し、必要に応じてanyOfで観測された型を組み合わせます。例のtags配列には文字列、null、整数があるため、要素スキーマはnullableな文字列またはnullableな整数を許可します。

nullや異なる型はどのように表されますか？

オブジェクトはプロパティを持つスキーマになります。同じ位置で観測されたすべてのオブジェクトに存在するプロパティは必須になります。異なる型が観測された値にはanyOfを使います。nullと別の型が観測された場合、型付きスキーマにnullable: trueを設定します。nullだけの値は型を推定できないため、制約のないスキーマになります。

生成される文書には何が含まれますか？

生成文書には1つのパス、選択したGET、POST、PUT、DELETEのいずれかのメソッド、成功時の200 JSONレスポンスが含まれます。スキーマはcomponentsに置かれ、レスポンスから参照されます。リクエスト本文、パラメーター、セキュリティ規則、エラーレスポンス、ヘッダーは生成しません。

IDのようなパスパラメーターを入力できますか？

パスは/api/usersのようにスラッシュで始まる固定のパスにしてください。/api/users/{id}のようなテンプレートには宣言されたパスパラメーターも必要ですが、この生成器は追加しないため、波括弧を含むパスは受け付けません。

完全なAPI契約を生成または検証しますか？

いいえ。出力はサンプルのレスポンス本文を記述します。リクエストスキーマの推定や、生成したYAMLとOpenAPI仕様の照合は行いません。他の操作やレスポンスの詳細を追加し、完成した文書をOpenAPIバリデーターで確認してください。

出典

OpenAPI Initiative: OpenAPI Specification 3.0.3