Как описать модель в Swagger для массива с простыми объектами?

Question

я отдыхаю услуг документировать, некоторые из них принимает простой массив, как:

[ 
    { "name":"a" }, 
    { "name":"b" }, 
    { "name":"c" } 
] 

Как описать это в модели раздела Swagger? Я могу создать только «по имени массива» как

model { 
properties: { "arr": { "type":"array", ...... 

но он описывает данные, как это:

"arr": [ 
    { "name":"a" }, 
    { "name":"b" }, 
    { "name":"c" } 
] 

Answer 1

Если я правильно понимаю, я думаю, что следующий может, что вы хотите.

Как уже упоминалось,

некоторые из них принимает простой массив

Тогда будет передаваться через параметр.

"parameters" : [{ 
    "name" : "param_name", 
    "type" : "array", 
    "items" : { 
    "$ref" : "M" 
    } 
    ... 
}] 
... 

Для модели раздела:

"models" : { 
    "M": { 
    "id" : "M", 
    "properties": { 
     "name" : { 
     "type" : "string" 
     } 
    } 
    } 

Answer 2

Это, вероятно, выглядит следующим образом:

... 
    "parameters" : [{ 
     "name" : "whatEverThatArrayCalled", 
     "type" : "array", 
     "items" : { 
     "$ref" : "whatEverThatArrayCalled" 
     } 
     ... 
    }], 
    "models" : { 
    { 
    "id" : "whatEverThatArrayCalled", 
    "properties": 
     { 
     "whatEverThatArrayCalled" : 
      { 
     "type" : "array", 
     "items":{"name":"a", 
        "name":"b", 
        "name":"c" 
        }, 

      } 
     } 
    } 
}   

...

Answer 3

Я попытался follwoing в на editor.swagger.io, он удовлетворяет просьбе этого вопроса и работает. Тело запроса POST ожидает массив. Массив состоит из элементов stackoverflow. Каждый элемент - это объект, имеющий свойство name.

paths: 
    /test: 
    post: 
     summary: test 123 
     description: test 123 
     parameters: 
     - name: param1 
      in: body 
      required: true 
      description: test param1 
      schema: 
      type: array 
      items: 
       $ref: '#/definitions/stackoverflow' 
     responses: 
     200: 
      description: OK 
definitions: 
    stackoverflow: 
    type: object 
    properties: 
     name: 
     type: string 
     description: name of the object 

Answer 4

Tony YUEN был близок, но не сигары. Это правильное определение с помощью YAML в OpenAPI/Swagger:

/test: 
post: 
    summary: test 123 
    description: test 123 
    parameters: 
    - name: param1 
     in: body 
     required: true 
     description: test param1 
     schema: 
      $ref: '#/definitions/stackoverflow' 
    responses: 
    200: 
     description: OK 

Это дает:

stackoverflow2[ 
    { 
    name: string 
    } 
] 

пример Тони производит:

[ 
    stackoverflow { 
       name: string 
    } 
] 

Полная Swagger/OpenAPI в YAML (копия & пасты)

swagger: '2.0' 

################################################################################ 
#        API Information         # 
################################################################################ 
info: 
    version: "Two-point-Oh!" 
    title: Simple objects in array test 
    description: | 
    Simple objects in array test 

################################################################################ 
#         Parameters         # 
################################################################################ 

paths: 
    /test: 
    post: 
     summary: Array with named objects 
     description: Array with named objects 
     parameters: 
     - name: param1 
      in: body 
      required: true 
      description: test param1 
      schema: 
      type: array 
      items: 
       $ref: '#/definitions/stackoverflow' 
     responses: 
     200: 
      description: OK 
    /test2: 
    post: 
     summary: Array with simpel (nameless) objects 
     description: Array with simpel (nameless) objects 
     parameters: 
     - name: param1 
      in: body 
      required: true 
      description: test param1 
      schema: 
       $ref: '#/definitions/stackoverflow2' 
     responses: 
     200: 
      description: OK 
definitions: 
    stackoverflow: 
    type: object 
    properties: 
     name: 
     type: string 
     description: name of the object 
    stackoverflow2: 
    type: array 
    items: 
     type: object 
     properties: 
     name: 
      type: string 
      description: name of the object 

Вот JSON-версия Swagger/OpenAPI

{ 
    "swagger" : "2.0", 
    "info" : { 
    "description" : "Simple objects in array test\n", 
    "version" : "Two-point-Oh!", 
    "title" : "Simple objects in array test" 
    }, 
    "paths" : { 
    "/test" : { 
     "post" : { 
     "summary" : "Array with named objects", 
     "description" : "Array with named objects", 
     "parameters" : [ { 
      "in" : "body", 
      "name" : "param1", 
      "description" : "test param1", 
      "required" : true, 
      "schema" : { 
      "type" : "array", 
      "items" : { 
       "$ref" : "#/definitions/stackoverflow" 
      } 
      } 
     } ], 
     "responses" : { 
      "200" : { 
      "description" : "OK" 
      } 
     } 
     } 
    }, 
    "/test2" : { 
     "post" : { 
     "summary" : "Array with simpel (nameless) objects", 
     "description" : "Array with simpel (nameless) objects", 
     "parameters" : [ { 
      "in" : "body", 
      "name" : "param1", 
      "description" : "test param1", 
      "required" : true, 
      "schema" : { 
      "$ref" : "#/definitions/stackoverflow2" 
      } 
     } ], 
     "responses" : { 
      "200" : { 
      "description" : "OK" 
      } 
     } 
     } 
    } 
    }, 
    "definitions" : { 
    "stackoverflow" : { 
     "type" : "object", 
     "properties" : { 
     "name" : { 
      "type" : "string", 
      "description" : "name of the object" 
     } 
     } 
    }, 
    "stackoverflow2" : { 
     "type" : "array", 
     "items" : { 
     "$ref" : "#/definitions/stackoverflow2_inner" 
     } 
    }, 
    "stackoverflow2_inner" : { 
     "properties" : { 
     "name" : { 
      "type" : "string", 
      "description" : "name of the object" 
     } 
     } 
    } 
    } 
} 

Answer 5

Вставить это http://editor.swagger.io/#/ и нажмите на "попробовать эту операцию"

{ 
    "swagger": "2.0", 
    "info": { 
    "version": "1.0.0", 
    "title": "Privacy-Service API" 
    }, 
    "paths": { 
    "/allNames": { 
     "post": { 
     "consumes": [ 
      "application/json" 
     ], 
     "produces": [ 
      "application/json" 
     ], 
     "parameters": [ 
      { 
      "name": "request", 
      "in": "body", 
      "schema": { 
       "$ref": "#/definitions/ArrayOfNames" 
      } 
      } 
     ], 
     "responses": { 
      "200": { 
      "description": "List of names", 
      "schema": { 
       "type": "array", 
       "items": { 
       "type": "string" 
       } 
      } 
      } 
     } 
     } 
    } 
    }, 
    "definitions": { 
    "ArrayOfNames": { 
     "type": "array", 
     "items": { 
     "minItems": 1, 
     "type": "object", 
     "required": [ 
      "name" 
     ], 
     "properties": { 
      "name": { 
      "type": "string" 
      } 
     } 
     } 
    } 
    } 
} 

Answer 6

parameters: 
    - name: "items" 
    in: "formData" 
    description: "description" 
    required: "true" 
    type: "array" 
    items: 
     type: "object" 
     additionalProperties: 
     properties: 
      name: 
      type: "string" 

По их документации https://swagger.io/docs/specification/data-models/dictionaries/, это должно привести к массив с объектами, которые имеют свойство с именем name и datatype, является строкой.
Он доступен по всему телу запросов, что-то вроде request.body.items

Update:

кажется, что это достаточно, чтобы сделать (без additionalproperties):

items: 
    type: object 
    properties: 
    name: 
     type: string 

Теперь вы получили элементы, в каждом из которых есть ключ с именем и соответствующее значение.

Если это, что TO просил ....