Skip to main content
Swagger
All documentation pages

OpenAPI 3.1 Domain Example

Below is an example of an OpenAPI 3.1 domain definition demonstrating various types of domain components.

For examples of domains in other supported protocols, refer to:

# OpenAPI version identifier - required for OpenAPI 3.1 domains
openapi: 3.1.0

#######################
# Optional info section
#######################
info:
  title: Acme Components
  summary: Common components for Acme REST APIs 
  description: Common components for Acme REST APIs
  version: _versionDef_
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html

components:

  ####################
  # Common data models
  ####################
  schemas:
    ErrorModel:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: [string, 'null']
          description: Additional error details

  ####################
  # Common parameters
  ####################
  parameters:
    offsetParam:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
      description: The number of items to skip before returning the results
      examples:
        default:
          value: 0
    limitParam:
      in: query
      name: limit
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 100
        default: 20
      description: The number of items to return
      examples:
        default:
          value: 20

  #######################
  # Common request bodies
  #######################
  requestBodies:
    NewItem:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            type: object
          examples:
            simple:
              value:
                name: Sample Item

  ####################
  # Common responses
  ####################
  responses:
    GeneralError:
      description: An error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorModel'
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'

  #########################
  # Common headers
  # (except request headers - they are defined as parameters)
  #########################
  headers:
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
      examples: 
        standard:
          value: 100
    X-RateLimit-Remaining:
      description: Remaining requests for the hour
      schema:
        type: integer
      examples:
        available:
          value: 94

  #######################
  # Common path items
  #######################
  pathItems:
    EntityOperations:
      get:
        summary: Get all items
        description: This operation supports pagination
        parameters:
          - $ref: '#/components/parameters/offsetParam'
          - $ref: '#/components/parameters/limitParam'
        responses:
          '200':
            description: A list of items
          default:
            $ref: '#/components/responses/GeneralError'
      post:
        summary: Add a new item
        requestBody:
          $ref: '#/components/requestBodies/NewItem'
        responses:
          '201':
            description: Created

  ######################################
  # Common examples of input/output data
  ######################################
  examples:
    tshirt:
      summary: Sample T-shirt data
      value:
        # Example value starts here
        id: 17
        name: T-shirt
        description: 100% cotton shirt
        categories: [clothes]

  links: {}
  callbacks: {}

See also

Was this page helpful?