OpenAPI 3.0 Domain Example

# OpenAPI version identifier - required for OpenAPI 3.0 domains
openapi: 3.0.0

#######################
# Optional info section
#######################
info:
  title: Acme Components
  description: Common components for Acme REST APIs
  version: 1.0.0

components:

  ####################
  # Common data models
  ####################
  schemas:
    ErrorModel:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string

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

  #######################
  # Common request bodies
  #######################
  requestBodies:
    NewItem:
      description: A JSON object containing item data
      required: true
      content:
        application/json:
          schema:
            type: object
          examples:
            tshirt:
              $ref: '#/components/examples/tshirt'

  ####################
  # 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
      example: 100
    X-RateLimit-Remaining:
      description: Remaining requests for the hour
      schema:
        type: integer
      example: 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
            headers:
              X-RateLimit-Limit:
                $ref: '#/components/headers/X-RateLimit-Limit'
              X-RateLimit-Remaining:
                $ref: '#/components/headers/X-RateLimit-Remaining'
          default:
            $ref: '#/components/responses/GeneralError'
      post:
        summary: Add a new item
        requestBody:
          $ref: '#/components/requestBodies/NewItem'
        responses:
          '201':
            description: Created
            headers:
              X-RateLimit-Limit:
                $ref: '#/components/headers/X-RateLimit-Limit'
              X-RateLimit-Remaining:
                $ref: '#/components/headers/X-RateLimit-Remaining'

  ######################################
  # 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]

  #########################
  # Common link definitions
  # See: https://swagger.io/docs/specification/links/
  #########################
  links: {}
  
  #########################
  # Common callback definitions
  # See: https://swagger.io/docs/specification/callbacks/
  #########################
  callbacks: {}