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

by

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

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to return an array of objects in SwaggerHub?
  3. How to document dynamic query parameter names in OpenAPI (Swagger)?
  4. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  5. How to define a property that can be string or null in OpenAPI (Swagger)?
  6. Swagger schema properties ignored when using $ref – why?
  7. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  8. Swagger 2.0: Multiple Path objects with different paths but same request and response
  9. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  10. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  11. Swagger: wildcard path parameters
  12. How to define an optional parameter in path using swagger
  13. Swagger: “equivalent path already exists” despite different parameters
  14. Re-using model with different required properties
  15. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  16. How not to copy-paste 3 generic error responses in almost all paths?
  17. How to define global parameters in OpenAPI?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. How to export swagger.json (or yaml)
  21. Swagger Inheritance and Composition
  22. Swagger/OpenAPI mock server
  23. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  24. Swagger HashMap property type
  25. Swagger: map of
  26. Use object type query param in swagger documentation
  27. Swagger complex response model with dynamic key value hash maps
  28. Combining defintions in Swagger docs
  29. How to document default None/null in OpenAPI/Swagger using FastAPI?
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment