OpenAPI / Swagger

How boringdocs works with OpenAPI and Swagger specifications.

Overview

If your project uses OpenAPI 3.x or Swagger 2.0, boringdocs can validate the spec against your actual implementation. This catches the common problem of specs drifting from the real API.

Setup

Point boringdocs at your OpenAPI spec:

docs:
  paths:
    - openapi.yaml
  format: openapi

What Gets Validated

Paths — Every path in the spec must exist in code, and vice versa
Operations — GET, POST, PUT, DELETE, PATCH must match actual endpoints
Parameters — Path, query, header, and body parameters must match
Schemas — Request/response schemas must match actual types
Examples — Examples in the spec must be valid against the schema

Spec-First vs Code-First

boringdocs supports both workflows:

Spec-first: You write the OpenAPI spec first, then implement. boringdocs checks that the implementation matches the spec.
Code-first: You write code and generate the spec. boringdocs checks that the generated spec is complete and accurate.

OpenAPI Extensions

boringdocs recognizes common extensions:

x-boringdocs-ignore — Skip validation for this path/operation
x-boringdocs-severity — Override severity for this path
x-boringdocs-group — Group related endpoints in reports

Example

paths:
  /users/{id}:
    get:
      summary: Get a user by ID
      x-boringdocs-severity: error
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'