0

I am trying to write Swagger documentation where two out of the five fields are required in a POST request. I've read a few options on how to do this, but can't seem to find a definitive answer.

Option 1: 

/my-endpoint:
post:
  x-swagger-router-controller: example.spec
  operationId: example_operationId
  parameters:
  - in: body
    name: recovery_data
    description: TODO
    schema:
      $ref: '#/definitions/RecoveryData'
    required: true
  responses:
    200:
      description: TODO
      schema:
        $ref: '#/definitions/OkResponse'

RecoveryData:
type: object
properties:
  required_field_1:
    description: TODO
    type: array
    required: true
  required_field_2:
    description: TODO
    type: string
    required: true
  optional_field_1:
    description: TODO
    type: boolean
    required: false
  optional_field_2:
    description: TODO
    type: boolean
    required: false
  optional_field_3:
    description: TODO
    type: boolean
    required: false
  optional_field_4:
    description: TODO
    type: string
    required: false

Option 2: 

 /my-endpoint:
post:
  x-swagger-router-controller: example.spec
  operationId: example_operationId
  parameters:
  - in: body
    name: recovery_data
    description: TODO
    schema:
      $ref: '#/definitions/RecoveryData'
  responses:
    200:
      description: TODO
      schema:
        $ref: '#/definitions/OkResponse'

RecoveryData:
type: object
properties:
  required_field_1:
    description: TODO
    type: array
    required: true
  required_field_2:
    description: TODO
    type: string
    required: true
  optional_field_1:
    description: TODO
    type: boolean
  optional_field_2:
    description: TODO
    type: boolean
  optional_field_3:
    description: TODO
    type: boolean
  optional_field_4:
    description: TODO
    type: string

In Option 1 I specify required: true in the parameters: part of the request, then write out which params are actually required or not in the schema. In option 2, I don't have required: true in the parameters, and then only write which fields are required.

Does anyone know which way is right?

Andrew Bresee
  • 1
  • Just to be clear, I know that `required: false` is the default. So I was wondering if leaving the params blank would make the whole POST body NOT required. Then if `required: true` would make the whole POST body required. – Andrew Bresee Jul 23 '18 at 18:45
  • Both examples are incorrect - `required` is not a property attribute, it's an object attribute containing a list of required properties. See the ^^ linked question. – Helen Jul 23 '18 at 20:17

1 Answers1

0

This is a bit of a duplicate to the question How to specify if a field is optional or required in swagger?

The answer seems to be:

RecoveryData:
  type: object
  required:
    - required_field_1
    - required_field_2
  properties:
    required_field_1:
      description: TODO
      type: array
    required_field_2:
      description: TODO
      type: string
    optional_field_1:
      description: TODO
      type: boolean
    optional_field_2:
      description: TODO
      type: boolean
    optional_field_3:
      description: TODO
      type: boolean
    optional_field_4:
      description: TODO
      type: string
Andrew Bresee
  • 1