Блог

Как определить в OpenAPI / Swagger, является ли поле необязательным или обязательным и какое значение по умолчанию?

По умолчанию поля в модели являются необязательными, если вы не помещаете их в required список. Ниже приведен пример — id , category являются необязательными полями, name является обязательным. Обратите внимание, что required это не атрибут полей, а атрибут самого объекта — это список обязательных свойств.

 type: object
required:  # List the required properties here
  - name
properties:
  id:
    type: integer
    format: int64
  category:
    $ref: '#/definitions/Category'
  name:
    type: string
    example: doggie
  

Ссылка: https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L658

Если это модель для тела запроса, вам, вероятно, также потребуется пометить само тело как required :

 # swagger: '2.0'

parameters:
  - in: body
    name: body
    required: true  # <----
    schema:
      $ref: '#/definitions/Pet'

# openapi: 3.x.x

requestBody:
  required: true  # <----
  content:
    ...
  

Чтобы указать значение по умолчанию для необязательных полей, вы можете использовать default атрибут. Вот пример:

 type: object
properties:
  huntingSkill:
    type: string
    description: The measured skill for hunting
    default: lazy
  

Поля являются необязательными, если не помечены как обязательные.

Вы перечисляете обязательные поля следующим образом:

 SomeObject:
    type: object
    required:
      - name
      - fartingPower
    properties:
      name:
        type: string
      fartingPower:
        type: integer
  

Альтернативный синтаксис:

 Response:
  type: object
  required: [id, title]
  properties:
    id:
      type: string
    title:
      type: string