How to specify if a field is optional or required in OpenAPI/Swagger?

Question

How to I define in OpenAPI/Swagger if a field is optional or required and what is the default?

Answer 1

By default, fields in a model are optional unless you put them in the required list. Below is an example - id, category are optional fields, name is required. Note that required is not an attribute of fields, but an attribute of the object itself - it's a list of required properties.

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

Ref: https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/test/resources/2_0/petstore.yaml#L658

If this is the model for the request body, you'll probably also need to mark the body itself as required:

# swagger: '2.0'  parameters:   - in: body     name: body     required: true  # <----     schema:       $ref: '#/definitions/Pet'  # openapi: 3.x.x  requestBody:   required: true  # <----   content:     ... 

To specify the default value of optional fields, you can use the default attribute. Here is an example:

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