Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

apidocs

API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs.

arbazkhan971 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add arbazkhan971/godmode --skill apidocs

About this skill


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:

# Template: OpenAPI 3.1 Spec-First
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:
# Composition with allOf
CreateUserRequest:
  allOf:

Step 5: Examples and Mocking

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

Step 6: Documentation Renderers

Set up interactive documentation from the OpenAPI spec:

Swagger UI

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");

Redoc

<!-- Static HTML — zero dependencies -->
<!DOCTYPE html>
<html>
# Build static docs
npx @redocly/cli build-docs openapi.yaml -o docs/index.html

Stoplight Elements

<!-- 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">

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:

# .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

Step 9: SDK Generation

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:

Step 10: Changelog Generation from Spec Diffs

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:

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.

  1. Every field gets a description and example. No guessing.
  2. $ref everything shared. No duplicate
Read the complete source ↗