OpenAPI: How to mark a schema field as required
22 January 2023 (Updated 22 January 2023)
Suppose you have a POST /v1/clients
endpoint that requires a JSON payload where the firstName
and lastName
fields are required, but email
is not. You can describe this with the following OpenAPI schema:
openapi: 3.0.3
info:
title: Client API - OpenAPI 3.0
description: |-
This is a sample API based on the OpenAPI 3.0 specification.
termsOfService: http://swagger.io/terms/
contact:
email: apiteam@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.11
servers:
- url: https://petstore3.swagger.io/api/v3
tags:
- name: client
description: Client operations
paths:
/clients:
post:
summary: Create a new client
tags:
- client
requestBody:
description: "The new client"
required: true
content:
application/json:
schema:
type: object
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
required:
- firstName
- lastName
responses:
201:
description: Client resource created
content:
application/json:
schema:
type: object
properties:
message:
type: string
Now, if you use a tool like Swagger UI, you’ll see that firstName
and lastName
fields are marked as required, but not email
.
![OpenAPI: How to mark a schema field as required](https://sajadtorkamani.com/wp-content/uploads/2023/01/Screenshot-2023-01-22-at-13.04.53.png)
You can paste the above YAML here to see the generated SwaggerUI docs.
Tagged:
OpenAPI
Thanks for your comment 🙏. Once it's approved, it will appear here.
Leave a comment