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: {}