[ADP-758] OpenAPI: $ref

Overview

In OpenAPI specifications, there are two primary methods for referencing reusable components:

1. Internal References: Using #/components/* within the same OpenAPI document.
2. External References: Using separate YAML files hosted on a public site or within the project repository.

Guidance

• SHOULD reuse components to keep the OpenAPI document clean.
• SHOULD favor published common YAML files for reuse purposes over components references.
• MUST follow ADP-24: Versioning Mechanism when updating schemas.
• SHOULD use ADP-701: Property Design principles when creating custom schemas.
• SHOULD use ADP-704: ID Field Convention in custom schemas.

Example: Defining and Using Internal References

• Defining Components:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

• Referencing Components:

paths:
  /users:
    get:
      summary: Retrieve all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

Example: Defining and Using External References

• User Schema in an External File (https://example.com/openapi/schema.yaml):

User:
  type: object
  properties:
    id:
      type: string
    name:
      type: string
    email:
      type: string

• Referencing the External Schema in the Main OpenAPI Document:

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Retrieve all users
      responses:
        '200':
          description: A list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: 'https://example.com/openapi/schema.yaml#/User'

Component Types

The components section can include various reusable elements:

Schemas

Define data models used in request and response bodies.

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

Responses

Define reusable response templates for common HTTP responses.

components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Parameters

Define reusable query parameters, path parameters, headers, etc.

components:
  parameters:
    PageSize:
      name: pageSize
      in: query
      description: Number of results to return per page
      required: false
      schema:
        type: integer
        default: 10

Examples

Provide examples for request bodies, responses, and parameters to illustrate usage.

components:
  examples:
    UserExample:
      summary: A user example
      value:
        id: '1'
        name: 'John Doe'
        email: 'john.doe@example.com'

Request Bodies

Define reusable request body structures.

components:
  requestBodies:
    UserRequest:
      description: User to create
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'

Headers

Define reusable headers.

components:
  headers:
    RateLimit:
      description: The number of allowed requests in the current period
      schema:
        type: integer

Security Schemes

Define reusable security schemes.

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Related ADPs

• ADP-24: Versioning Mechanism
• ADP-701: Property Design
• ADP-704: ID Field Convention
• ADP-751: New OpenAPI Document

References

• OpenAPI Specification
• JSON Schema
• YAML Specification

INFO

💡 Certain OpenAPI edit tool doesn't support editing the #/components/parameters field of the OpenAPI document; furthermore, we assume OpenAPI documents could be owned/managed by different groups in the business unit/company.