如何大摇大摆地描述 json 数组？

Question

假设我有一个像这样的 json :

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

我如何用 swagger（最好是 swagger-lume）来描述它？

Answer 1

要大摇大摆地描述 "cars" 对象，首先在 Json 模式中对其进行建模可能是一个方便的技巧：

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

this json represents a request body, and is submited via post

然后您可以在定义 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"
   ]
}

如何大摇大摆地描述 json 数组？

How to describe json array in swagger?

swagger

lumen