How to specify if a field is optional or required in OpenAPI/Swagger?
Fields are optional unless marked as required.
You list required fields like this:
SomeObject:
type: object
required:
- name
- fartingPower
properties:
name:
type: string
fartingPower:
type: integer
An alternative syntax:
Response:
type: object
required: [id, title]
properties:
id:
type: string
title:
type: string
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