Ввод массивов внутри объектов с использованием Swagger 2.0 и YAML

Question

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

Я читал онлайн, что использование YAML легче читать, чем с помощью JSON, и поскольку YAML является подмножеством JSON, я полагал, что все будет в порядке.

Я работаю над ответом на 200 кода, я хотел бы представлять собой нечто похожее на следующую структуру:

responses: 
    200: 
     description: OK. 
     schema: 
     title: response 
     type: object 
     items: 
      properties: 
      title: user 
      type: array 
      items: 
       id: 
        type: string 
       name: 
        type: string 
      status: 
       type: integer 

В основном я возвращаю объект под названием «ответ», который содержит две переменные: массив, называемый «пользователь», который содержит несколько строк (для ясности я включил только два) и другую переменную (вне «пользовательского» массива), называемую «статус», которая содержит целое число.

Вышеупомянутый код не работает, и редактор уведомляет меня о том, что он не является «правильным определением ответа».

Я не уверен, как это решить. Я был бы признателен за помощь в том, что я делаю неправильно.

Answer 1

В основном я возвращаю объект, называемый «ответ», который содержит две переменные: массив под названием «пользователь», который содержит несколько строк (я включал только два для ясности) и другие переменного (за пределами «пользователя «массив», называемый «статус», который содержит целое число.

На основании вашего описания ответ должен быть следующим (при условии, что ответ JSON). В принципе, у вас есть объект с вложенным объектом:

{ 
    "user": { 
    "id": "12345", 
    "name": "Alice" 
    }, 
    "status": 0 
} 

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

 responses: 
     200: 
      description: OK. 
      schema: 
      title: response 
      type: object 
      required: [user, status] 
      properties: 
       user: 
       type: object 
       required: [id, name] 
       properties: 
        id: 
        type: string 
        name: 
        type: string 
       status: 
       type: integer 

Для удобства, сложные схемы с вложенными объектами могут быть разбиты на отдельные схемы объекта. Схемы можно записать в глобальном разделе definitions и ссылаться из других мест через $ref. Таким образом, например, вы можете повторно использовать одну и ту же схему в нескольких операциях/ответах.

 responses: 
     200: 
      description: OK. 
      schema: 
      $ref: "#/definitions/ResponseModel" 

definitions: 
    ResponseModel: 
    title: response 
    type: object 
    properties: 
     user: 
     $ref: "#/definitions/User" 
     status: 
     type: integer 
    required: 
     - user 
     - status 

    User: 
    type: object 
    properties: 
     id: 
     type: string 
     name: 
     type: string 
    required: 
     - id 
     - name