OpenAPI: How to mark a schema field as required

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

You can paste the above YAML here to see the generated SwaggerUI docs.

Tagged: OpenAPI

Leave a comment Cancel reply