Как описать массив JSON в Swagger?

Question

Допустим, у меня есть такой json:

{
    "cars": [
        { "name":"Ford", "models":[ "Fiesta", "Focus", "Mustang" ] },
        { "name":"BMW", "models":[ "320", "X3", "X5" ] },
        { "name":"Fiat", "models":[ "500", "Panda" ] }
    ]
}

Как мне описать это в чванстве (желательно чванство-люме)?

Answer 1

Чтобы описать объект "cars" в swagger, может оказаться удобным сначала смоделировать его в Json Schema:

{
   "type":"array",
   "items":{
      "type":"object",
      "required":[
         "name",
         "models"
      ],
      "properties":{
         "name":{
            "type":"string"
         },
         "models":{
            "type":"array",
            "items":{
               "type":"string"
            }
         }
      }
   }
}

этот json представляет тело запроса и являетсяотправленный по почте

Затем вы можете обратиться к этой модели при определении операции HTTP:

{
   "swagger":"2.0",
   "info":{
      "description":"My Cars definition\n",
      "version":"1.0.0",
      "title":"Cars"
   },
   "paths":{
      "/postMyCars":{
         "post":{ // <-- HTTP post
            "summary":"Post my cars in!",
            "consumes":[
               "application/json"
            ],
            "parameters":[
               {
                  "name":"cars",
                  "in":"body", // <-- in request body
                  "description":"Cars to add to the system",
                  "required":true,
                  "schema":{ // <-- define your cars payload here
                     "type":"array",
                     "items":{
                        "type":"object",
                        "required":[
                           "name",
                           "items"
                        ],
                        "properties":{
                           "name":{
                              "type":"string"
                           },
                           "models":{
                              "type":"array",
                              "items":{
                                 "type":"string"
                              }
                           }
                        }
                     }
                  }
               }
            ],
            "responses":{
               "200":{
                  "description":"Cars OK"
               }
            }
         }
      }
   },
   "schemes":[
      "https",
      "http"
   ]
}