Swaggerで複雑なJSONモデルを記述する方法
Swaggerを使用して、作成中のweb-apiを記述しようとしています。問題は、複雑なJSONオブジェクトを記述する方法を理解できないことです。
たとえば、このオブジェクトの記述方法:
{
name: "Jhon",
address: [
{
type: "home",
line1: "1st street"
},
{
type: "office",
line1: "2nd street"
}
]
}
さて、上のコメントに基づいて、次のスキーマが必要になります。
{
"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"
}
}
}
}
}
}
}
}