web-dev-qa-db-ja.com

Swaggerで複雑なJSONモデルを記述する方法

Swaggerを使用して、作成中のweb-apiを記述しようとしています。問題は、複雑なJSONオブジェクトを記述する方法を理解できないことです。

たとえば、このオブジェクトの記述方法：

{
  name: "Jhon",
  address: [
    {
      type: "home",
      line1: "1st street"
    },
    {
       type: "office",
       line1: "2nd street"
    }
  ]
}
swaggerswagger-ui
30
Ido Ran

さて、上のコメントに基づいて、次のスキーマが必要になります。

{
  "definitions": {
    "user": {
      "type": "object",
      "required": [ "name" ],
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/address"
          }
        }
      }
    },
    "address": {
        "type": "object",
        "properties": {
            "type": {
                "type": "string",
                "enum": [ "home", "office" ]
            },
            "line1": {
                "type": "string"
            }
        }
    }
  }
}

サンプルをもう少し複雑にし、将来的に役立つように、いくつかの仮定をしました。 「ユーザー」オブジェクトの場合、「名前」フィールドは必須であると宣言しました。たとえば、住所も必須にする必要がある場合は、定義を「必須」に変更できます：["name"、 "address"]。

基本的に、json-schemaのサブセットを使用してモデルを記述します。もちろん、誰もがそれを知っているわけではありませんが、学習して使用するのはかなり簡単です。

アドレスの種類については、自宅またはオフィスの2つのオプションに制限を設定していることがわかります。そのリストに何かを追加するか、「enum」を完全に削除してその制約を削除できます。

プロパティの「タイプ」が「配列」である場合、配列の内部タイプを宣言する「アイテム」を伴う必要があります。この場合、別の定義を参照しましたが、その定義もインラインにすることができました。特に「アドレス」の定義が単独で、または他のモデル内で必要な場合は、通常、この方法を維持する方が簡単です。

要求に応じて、インラインバージョン：

{
  "definitions": {
    "user": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "address": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "home",
                  "office"
                ]
              },
              "line1": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
41
Ron