Menú
API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
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.
Basado en la clasificación ocupacional SOC
| 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.