| name | apidocs |
| description | API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs. |
APIDocs — Documentation Generation & Interactive Specs
Activate When
- User invokes
/godmode:apidocs
- User says "generate API docs", "write OpenAPI spec", "set up Swagger"
- User says "add Redoc", "create API reference", "document my API"
- User says "auto-generate docs from code", "set up interactive docs"
- When
/godmode:api finishes and documentation needs to be published
- When
/godmode:review flags missing or outdated API documentation
- When a codebase has API routes but no corresponding spec or docs
Workflow
Step 1: Discovery & Approach Selection
Determine the documentation strategy before generating anything:
APIDOCS DISCOVERY:
Project: <name and purpose>
Language/Framework: <Node/Express, Python/FastAPI, Java/Spring, Go, NestJS, etc.>
If the user hasn't specified, ask: "Do you want to write the spec first and generate code from it
(spec-first), or generate the spec from existing code (code-first)?"
Step 2: Spec-First — Writing OpenAPI from Scratch
For spec-first (contract-first) development, produce a complete OpenAPI document:
openapi: "3.1.0"
info:
Rules for spec-first:
- Write the spec BEFORE any implementation. The spec is the contract.
- Every field must have a
description and an example.
- Use
$ref aggressively — never duplicate schema definitions.
- Group related endpoints under
tags.
- Provide
examples for every request body and response.
- Include
servers for all environments.
- Add
x- extensions for renderer-specific features (Redoc logo, Stoplight groups).
Step 3: Code-First — Auto-Generate Spec from Code
For code-first, configure the framework's doc generation:
CODE-FIRST SETUP BY FRAMEWORK:
Framework-specific setup:
- Express:
swagger-jsdoc + swagger-ui-express with JSDoc @openapi annotations
- NestJS:
@nestjs/swagger with DocumentBuilder and ApiProperty decorators
- FastAPI: Built-in OpenAPI generation from Pydantic models
- Spring Boot:
springdoc-openapi with @Tag, @Operation annotations
- tsoa: TypeScript decorators,
npx tsoa spec generates spec
- Go:
swaggo/swag with comment annotations, swag init generates spec
Step 4: Schema Reuse with $ref and Components
Enforce DRY specs by extracting shared schemas:
SCHEMA REUSE CHECKLIST:
| Pattern | Extract to |
Rules:
- If a schema appears in 2+ places, extract it to
components/schemas.
- Pagination parameters go in
components/parameters — never inline them.
- Error responses go in
components/responses — reference everywhere.
- Use
allOf for composition and oneOf/anyOf for polymorphism:
CreateUserRequest:
allOf:
Step 5: Examples and Mocking
Every operation must have realistic examples for documentation and mocking:
properties:
email:
Mock server setup:
npm install -g @stoplight/prism-cli
prism mock openapi.yaml
Step 6: Documentation Renderers
Set up interactive documentation from the OpenAPI spec:
Swagger UI
npm install swagger-ui-express
docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml \
const swaggerUi = require("swagger-ui-express");
const spec = require("./openapi.json");
Redoc
<!DOCTYPE html>
<html>
npx @redocly/cli build-docs openapi.yaml -o docs/index.html
Stoplight Elements
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
Step 7: Versioning in Specs
Handle API versioning within OpenAPI specs:
SPEC VERSIONING STRATEGIES:
| Strategy | How to Represent in OpenAPI |
Step 8: CI Validation & Linting
Validate specs in CI to prevent regressions:
name: API Docs CI
on:
extends: ["spectral:oas"]
npx @useoptic/optic diff openapi.yaml --base main --check
Step 9: SDK Generation
Generate client SDKs from the OpenAPI spec:
npm install -g @openapitools/openapi-generator-cli
npx openapi-typescript openapi.yaml -o src/api/schema.d.ts
name: Generate SDKs
on:
Step 10: Changelog Generation from Spec Diffs
Automatically generate API changelogs from spec differences:
npm install -g oasdiff
CHANGELOG OUTPUT EXAMPLE:
API Changelog: v1.0.0 → v2.0.0
name: API Changelog
on:
Step 11: Validation & Quality Gate
Validate the documentation setup against completeness standards:
APIDOCS VALIDATION:
| Check | Status |
Step 12: Deliverables
Generate the final artifacts:
APIDOCS COMPLETE:
Artifacts:
Commit: "apidocs: <service> — OpenAPI spec, <renderer> setup, CI validation configured"
Key Behaviors
IF Spectral lint errors > 0: fix before merging.
WHEN breaking changes detected by oasdiff: block PR, require migration plan.
IF schema coverage < 100% (fields without descriptions): add descriptions.
- Every field gets a description and example. No guessing.
- $ref everything shared. No duplicated schemas.
- Validate in CI. Spectral + Optic + Redocly on every PR.
- Realistic examples.
"jane.doe@example.com" not "string".
- Generate from code when code exists. Spec-first for greenfield.
- Publish docs automatically. Deploy on every merge.
- Track breaking changes. Spec diff in CI catches regressions.
HARD RULES
Never ask to continue. Loop autonomously until spec validates and all endpoints have examples.
- NEVER write endpoint docs without realistic examples. A schema without examples is a guessing game.
Every request and response must have at least one realistic example.
- NEVER duplicate schemas. Extract shared shapes to
components/schemas and use $ref. Duplicated schemas drift.
- NEVER skip CI validation. Lint and validate the OpenAPI spec on every PR. A spec valid last week can break today.
- NEVER hand-edit generated specs in code-first workflows. Modify annotations in code instead. The
generator overwrites manual edits.
- NEVER ignore breaking changes. Use Optic or oasdiff in CI to catch removed endpoints, renamed
parameters, and type changes.
- NEVER skip security scheme documentation. Undocumented auth forces every consumer to reverse-engineer
your auth flow.
- ALWAYS serve docs in all environments or publish static docs. Docs behind
if (env === 'development')
are invisible to production consumers.
- ALWAYS use
example: with realistic values -- "jane.doe@example.com" not "string".
TSV Logging
Log every invocation to .godmode/ as TSV. Create on first run.
timestamp skill action endpoints schemas lint_errors breaking_changes status
2026-03-20T14:00:00Z apidocs generate_spec 12 8 0 0 pass
2026-03-20T14:10:00Z apidocs validate 12 8 2 1 needs_fix
Quality Targets
- Target: 100% endpoint coverage in documentation
- Target: >90% of examples return 2xx on test run
- Target: <30s to find any endpoint in docs
- Max response example size: <50KB per endpoint
Success Criteria
The apidocs skill is complete when ALL of the following are true:
- Valid OpenAPI 3.0/3.1 spec that parses without errors
- All operations have descriptions, tags, and at least one example
- All schemas have field descriptions and realistic examples
- $ref is used for all shared schemas (no duplicated definitions)
- Error responses defined on all endpoints (401, 400, 500 at minimum)
- Security schemes documented and applied to endpoints
- Spectral lint passes with zero errors
- No breaking changes vs main branch (or breaking changes are documented)
- Doc renderer builds and displays correctly
Iterative Loop Protocol
max_iterations = 12
WHILE doc_tasks remain:
1. MEASURE: validate spec, check examples
2. KEEP if: 0 lint errors AND 0 breaking changes
3. DISCARD if: validation fails OR examples broken
4. COMMIT kept changes. Revert discarded.
Keep/Discard
KEEP if: improvement verified. DISCARD if: regression or no change. Revert discards immediately.
Stop Conditions
STOP when ANY of these are true:
- All identified tasks are complete and validated
- User explicitly requests stop
- Max iterations reached — report partial results with remaining items listed
DO NOT STOP only because:
- One item is complex (complete the simpler ones first)
- A non-critical check is pending (handle that in a follow-up pass)
Error Recovery
| Failure | Action |
|---|
| OpenAPI spec validation fails | Run swagger-cli validate to get specific errors. Fix schema references, missing required fields, and invalid types. |
| Generated docs drift from implementation | Add CI check: compare spec against route handlers. Use spec-first or code-first consistently, never mix. |
| Examples fail validation against schema | Verify example values match declared types, enums, and patterns. Auto-generate examples from schema as fallback. |
| Docs build breaks after API change | Pin docs generator version. Run docs build in CI on every PR that touches API routes. |
Output Format
Print: `APIDocs: {endpoints} endpoints documented. Schema valid: {yes|no}. Examples: {N}/{M} passing.
