Menu
API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Turn on Godmode. 134 skills, 7 subagents, zero configuration. Routes to the right skill automatically.
Accessibility. WCAG 2.1 AA/AAA, a11y audit, color contrast, keyboard navigation, screen reader, Axe, Pa11y, Lighthouse.
Cache. Redis, Memcached, Varnish, CDN, cache invalidation, TTL, write-through, cache stampede, thundering herd.
Config. dev/staging/prod, feature flags, A/B test rollout, config validation, env parity, secret safety, drift detection.
Crypto. encryption, hashing, Argon2, bcrypt, key management, JWT signing, TLS hardening, digital signatures, sensitive data.
Docs. OpenAPI/Swagger, JSDoc, docstrings, README, runbook, API docs, stale docs audit, missing coverage.
| name | apidocs |
| description | API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs. |
/godmode:apidocs/godmode:api finishes and documentation needs to be published/godmode:review flags missing or outdated API documentationDetermine 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)?"
For spec-first (contract-first) development, produce a complete OpenAPI document:
# Template: OpenAPI 3.1 Spec-First
openapi: "3.1.0"
info:
Rules for spec-first:
description and an example.$ref aggressively — never duplicate schema definitions.tags.examples for every request body and response.servers for all environments.x- extensions for renderer-specific features (Redoc logo, Stoplight groups).For code-first, configure the framework's doc generation:
CODE-FIRST SETUP BY FRAMEWORK:
Framework-specific setup:
swagger-jsdoc + swagger-ui-express with JSDoc @openapi annotations@nestjs/swagger with DocumentBuilder and ApiProperty decoratorsspringdoc-openapi with @Tag, @Operation annotationsnpx tsoa spec generates specswaggo/swag with comment annotations, swag init generates specEnforce DRY specs by extracting shared schemas:
SCHEMA REUSE CHECKLIST:
| Pattern | Extract to |
Rules:
components/schemas.components/parameters — never inline them.components/responses — reference everywhere.allOf for composition and oneOf/anyOf for polymorphism:# Composition with allOf
CreateUserRequest:
allOf:
Every operation must have realistic examples for documentation and mocking:
# Inline examples in schema
properties:
email:
Mock server setup:
# Prism — mock server from OpenAPI spec
npm install -g @stoplight/prism-cli
prism mock openapi.yaml # Start mock server on :4010
Set up interactive documentation from the OpenAPI spec:
npm install swagger-ui-express
# or standalone
docker run -p 8080:8080 -e SWAGGER_JSON=/spec/openapi.yaml \
// Express integration
const swaggerUi = require("swagger-ui-express");
const spec = require("./openapi.json");
<!-- Static HTML — zero dependencies -->
<!DOCTYPE html>
<html>
# Build static docs
npx @redocly/cli build-docs openapi.yaml -o docs/index.html
<!-- Embed in any HTML page -->
<script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
Handle API versioning within OpenAPI specs:
SPEC VERSIONING STRATEGIES:
| Strategy | How to Represent in OpenAPI |
Validate specs in CI to prevent regressions:
# .github/workflows/api-docs.yml
name: API Docs CI
on:
# .spectral.yaml — custom linting rules
extends: ["spectral:oas"]
# Optic — track breaking changes over time
npx @useoptic/optic diff openapi.yaml --base main --check
Generate client SDKs from the OpenAPI spec:
# openapi-generator — supports 50+ languages
npm install -g @openapitools/openapi-generator-cli
# Alternative: openapi-typescript (lightweight, type-only)
# Generates TypeScript types from OpenAPI — no runtime, types only
npx openapi-typescript openapi.yaml -o src/api/schema.d.ts
# CI workflow for SDK generation
name: Generate SDKs
on:
Automatically generate API changelogs from spec differences:
# oasdiff — diff two OpenAPI specs and generate changelog
npm install -g oasdiff
# or
CHANGELOG OUTPUT EXAMPLE:
API Changelog: v1.0.0 → v2.0.0
# CI: auto-generate changelog on spec changes
name: API Changelog
on:
Validate the documentation setup against completeness standards:
APIDOCS VALIDATION:
| Check | Status |
Generate the final artifacts:
APIDOCS COMPLETE:
Artifacts:
Commit: "apidocs: <service> — OpenAPI spec, <renderer> setup, CI validation configured"
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.
"jane.doe@example.com" not "string".Never ask to continue. Loop autonomously until spec validates and all endpoints have examples.
components/schemas and use $ref. Duplicated schemas drift.if (env === 'development')
are invisible to production consumers.example: with realistic values -- "jane.doe@example.com" not "string".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
The apidocs skill is complete when ALL of the following are true:
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 if: improvement verified. DISCARD if: regression or no change. Revert discards immediately.
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)
| 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. |
Print: `APIDocs: {endpoints} endpoints documented. Schema valid: {yes|no}. Examples: {N}/{M} passing.