Имеются массивы в массивах в ответах Swagger

Question

Я пытаюсь определить API в Swagger, где результат GET - это массив элементов для модели MainModel, каждый из которых связан с массивом элементов из другой модели под названием AnotherModel. Что-то вроде этого (который, кажется, не допускается):

responses: 
    200: 
     description: search results matching criteria 
     schema: 
     type: array 
     items: 
      $ref: '#/definitions/MainModel' 
      type: array 
      items: $ref: '#/definitions/AnotherModel' 

Answer 1

Прежде всего, Форс поддерживает только ассоциативные массивы, где ключи являются строками, например:

{ 
    "foo": 5, 
    "bar": 2 
} 

но не С # Dictionary<int, string> где ключи int.

Ассоциативный массив определяется с помощью схемы object с ключевым словом additionalProperties, определяющим тип значений массива. Тип ключа не упоминается, поскольку ключи всегда являются строками.

type: object 
additionalProperties: 
    type: <type of array values> 
    # OR 
    # $ref: '#/definitions/ValueModel' 

Аналогично, массив ассоциативных массивов может быть определен следующим образом:

type: array 
items: 
    type: object 
    additionalProperties: 
    type: <type of values in associative array> 
    # OR 
    # $ref: '#/definitions/ValueModel' 

В вашем примере, значение ассоциативного массива имеет типа AnotherModel. Так что определение рядный будет выглядеть следующим образом:

 responses: 
     200: 
      description: search results matching criteria 
      schema: 
      type: array 
      items: 
       type: object 
       additionalProperties: 
       $ref: '#/definitions/AnotherModel' 

definitions: 
    AnotherModel: 
    type: <whatever> # TODO 

Или, если ввести промежуточный MainModel, представляющий ассоциативный массив (как в исходном примере):

 responses: 
     200: 
      description: search results matching criteria 
      schema: 
      type: array 
      items: 
       $ref: '#/definitions/MainModel' 

definitions: 
    MainModel: # Associative array of AnotherModel 
    type: object 
    additionalProperties: 
     $ref: '#/definitions/AnotherModel' 
    AnotherModel: 
    type: <whatever> # TODO 

Несколько примечаний:

• Каждая модель, на которую ссылаются через $ref, должна быть определена в разделе definitions. Так что если вы используете $ref: '#/definitions/MainModel', ваша спецификация должна включать в себя

  definitions: 
      MainModel: 
  

• $ref работы, заменив себя и все свои одноуровневые элементы с определением она, указывая на. Вот почему ваш оригинальный пример не является действительным:

  items: 
      $ref: '#/definitions/MainModel' 
      type: array 
      items: $ref: '#/definitions/AnotherModel' 
  

  Вложенные модели могут быть либо определены полностью рядный или ссылки через $ref, но не оба.