OpenAPI Spec Writer

OpenAPI Spec Writer

Prerequisites & Dependencies

• Read access to the backend source: router/controller + validation/schema annotations
• Node 18+ with npm i -g @redocly/cli or @stoplight/spectral-cli for lint/preview
• Framework-generated annotations (FastAPI, NestJS, SpringDoc) as ground-truth DTO references if available

Execution Steps

1. Inventory all routes: HTTP method, path (convert framework placeholders to {param}), assigned tags, and auth requirements from middleware/decorators.
2. Extract request contracts: path/query/header parameters, request body schema, content types — read from validators or DTOs, never guess.
3. Extract response contracts: status codes, response shapes, error envelope structure; promote reused models to components/schemas.
4. Document auth under components/securitySchemes and indicate global vs per-operation security requirements.
5. Assemble openapi.yaml (3.0.3) with info, servers (dev/staging/prod), consistent operationIds, and full path/item documentation.
6. Lint and fix: spectral lint openapi.yaml; preview with redocly preview-docs and verify all operations render correctly.

openapi: 3.0.3
info: { title: Orders API, version: 1.2.0 }
servers: [{ url: https://api.example.com/v1 }]
paths:
  /orders/{id}:
    get:
      operationId: getOrder
      tags: [orders]
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        "200": { description: OK, content: { application/json: { schema: { $ref: "#/components/schemas/Order" } } } }
        "404": { $ref: "#/components/responses/NotFound" }
components:
  securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT } }
  schemas:
    Order:
      type: object
      required: [id, status]
      properties: { id: { type: string, format: uuid }, status: { type: string, enum: [open, paid, shipped] } }

spectral lint openapi.yaml
redocly preview-docs openapi.yaml