Reusable Schemas, Examples and Shared Components

Large APIs need shared building blocks: common schemas (Money, Problem, PageInfo), parameters (Limit, Cursor), responses (NotFound, RateLimited) and headers (RateLimit, Idempotency-Key). Keep them in a shared component library referenced with $ref across specs, bundle for publishing (Redocly CLI), and include realistic examples for every schema — they power docs, mocks and tests.

# shared/components.yaml
components:
  parameters:
    Limit: { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
    Cursor: { name: cursor, in: query, schema: { type: string } }
    IdempotencyKey: { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
  responses:
    RateLimited:
      description: Too many requests
      headers: { Retry-After: { schema: { type: integer } } }
      content: { application/problem+json: { schema: { $ref: "#/components/schemas/Problem" } } }
  schemas:
    Money:
      type: object
      required: [amount, currency]
      properties: { amount: { type: integer }, currency: { type: string, pattern: "^[A-Z]{3}$" } }
      examples: [{ amount: 1299, currency: EUR }]

# orders.yaml
parameters: [{ $ref: "../shared/components.yaml#/components/parameters/Limit" }]

# bundle: npx @redocly/cli bundle orders.yaml -o dist/orders.yaml

Common pitfalls

• Copy-pasted schemas drifting apart.
• Examples that don't validate against their schemas.
• Monolithic 20,000-line spec files nobody can review.

Key points

• Shared components library
• Examples for everything
• Split, then bundle for publishing

Further reading: Redocly CLI: bundle