Documentation Examples

# Validate the spec with Redocly (recommended)
npx @redocly/cli lint openapi-spec/openapi.yaml

# Preview rendered documentation in browser
npx @redocly/cli preview-docs openapi-spec/openapi.yaml

# Generate HTML docs
npx @redocly/cli build-docs openapi-spec/openapi.yaml -o docs/

# Validate with Spectral (alternative linter)
npx @stoplight/spectral-cli lint openapi-spec/openapi.yaml

# Define once in components
components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

# Reference everywhere
paths:
  /orders/{id}:
    get:
      responses:
        "404":
          $ref: "#/components/responses/NotFound"

components:
  schemas:
    PaginatedOrders:
      type: object
      required: [data, total, page, limit]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Order"
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

# .github/workflows/docs.yml
- name: Lint OpenAPI spec
  run: npx @redocly/cli lint openapi-spec/openapi.yaml --fail-on-warnings