30

私が構築している web-api を記述するために Swagger を使用しようとしています。問題は、複雑な json オブジェクトを記述する方法を理解できないことですか?

たとえば、このオブジェクトを記述する方法は次のとおりです。

{
  name: "Jhon",
  address: [
    {
      type: "home",
      line1: "1st street"
    },
    {
       type: "office",
       line1: "2nd street"
    }
  ]
}
4

1 に答える 1

41

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

{
  "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"
            }
        }
    }
  }
}

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

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

住所の種類については、自宅とオフィスの 2 つのオプションに制限を設定しています。そのリストに何かを追加するか、「列挙型」を完全に削除してその制約を削除できます。

プロパティの「型」が「配列」の場合、配列の内部型を宣言する「項目」を付随させる必要があります。この場合、別の定義を参照しましたが、その定義もインラインである可能性があります。特に「アドレス」定義だけが必要な場合や、他のモデル内で必要な場合は、通常はそのように維持する方が簡単です。

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

{
  "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"
              }
            }
          }
        }
      }
    }
  }
}
于 2014-10-17T12:41:50.653 に答える