apidocs
API documentation. OpenAPI, Swagger, Redoc, contract-first development, spec-first, code-first, interactive docs.
arbazkhan971 · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add arbazkhan971/godmode --skill apidocs技能说明
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:apifinishes and documentation needs to be published - When
/godmode:reviewflags 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
descriptionand anexample. - Use
$refaggressively — never duplicate schema definitions. - Group related endpoints under
tags. - Provide
examplesfor every request body and response. - Include
serversfor 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-expresswith JSDoc@openapiannotations - NestJS:
@nestjs/swaggerwithDocumentBuilderandApiPropertydecorators - FastAPI: Built-in OpenAPI generation from Pydantic models
- Spring Boot:
springdoc-openapiwith@Tag,@Operationannotations - tsoa: TypeScript decorators,
npx tsoa specgenerates spec - Go:
swaggo/swagwith comment annotations,swag initgenerates 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
allOffor composition andoneOf/anyOffor 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.
- Every field gets a description and example. No guessing.
- $ref everything shared. No duplicate