api-docs-weapon

name

api-docs-weapon

description

API documentation authority — Swagger UI / Redoc / Scalar / Mintlify / Stoplight / Bump.sh tool selection, OpenAPI spec enrichment with JSON examples, self-hosted and managed hosting, SDK generation (TypeScript / Python / Go via openapi-generator-cli and Fern/Speakeasy), and changelog discipline. Invoke when the user says "set up API docs", "which docs renderer should I use", "generate an SDK from my spec", "deploy my OpenAPI docs", "write an API changelog", "compare Redoc vs Scalar", or "publish API reference to GitHub Pages". Do NOT invoke for general documentation sites (library-guardian), API security scheme audits (security-guardian), or backend route design (python-guardian / react-guardian).

api-docs-weapon

Procedural arsenal for api-docs-guardian, the Legion AI Tools Factory's API documentation specialist. This weapon encodes the tool comparison matrix, the example-authoring discipline, the deployment playbooks for all major hosting targets, the SDK generation pipelines, and the changelog discipline that keeps API consumers informed without breaking them.

When this weapon applies

Load this weapon when api-docs-guardian is invoked. Typical triggers:

• "Set up API docs for this project."
• "Which renderer should I use — Redoc or Scalar?"
• "Deploy my OpenAPI spec to GitHub Pages."
• "Generate a TypeScript SDK from my spec."
• "Write a changelog entry for this breaking API change."
• "Audit our existing API docs."
• "Add examples to every endpoint."

Do NOT load it for:

• Full documentation sites beyond the API reference (route to library-guardian).
• OpenAPI security scheme audits (route to security-guardian).
• REST/GraphQL route design (route to python-guardian or react-guardian).
• CI/CD pipeline design for the docs deployment (route to devops-guardian; this weapon provides the workflow file template but does not architect the full pipeline).

First action when this weapon is loaded

Read these in order before doing anything else:

1. guides/00-principles.md — the spec-first mindset, the five quality gates, when to route elsewhere, and the core invariants.
2. guides/01-tool-selection.md — the full tool comparison matrix and decision tree. Read this before recommending any renderer.
3. research/research-summary.md — the intelligence gathered by scripture-historian covering Scalar, Redoc, Mintlify, SDK generators, and changelog tooling.

Then walk the remaining guides in task order. Each guide is short; the substantive intelligence comes from the research notes under research/external/.

Folder layout

api-docs-weapon/
├── SKILL.md                          (this file)
├── README.md                         (one-page human overview)
├── guides/
│   ├── 00-principles.md              (spec-first mindset, five quality gates, scope boundary)
│   ├── 01-tool-selection.md          (comparison matrix: Scalar / Redoc / Swagger UI / Mintlify / Stoplight / Bump.sh)
│   ├── 02-examples.md                (JSON example authoring; x-examples; overlay files)
│   ├── 03-deployment.md              (GitHub Pages / Netlify / Vercel / self-hosted Docker)
│   ├── 04-sdk-generation.md          (openapi-generator-cli / Fern / Speakeasy; TypeScript / Python / Go)
│   ├── 05-changelog.md               ([BREAKING] convention; impact-first format; Bump.sh CI gate)
│   └── 06-done-checklist.md          (10-point validation before docs go live)
├── examples/
│   ├── scalar-github-pages-setup.md  (end-to-end Scalar + GitHub Pages for a TypeScript API)
│   ├── redoc-self-hosted-docker.md   (Redoc in multi-stage Dockerfile)
│   ├── fern-typescript-sdk.md        (Fern SDK generation from an existing OpenAPI spec)
│   └── api-changelog-entry.md        (before/after changelog entry for a breaking endpoint rename)
├── templates/
│   ├── redoc-config.yaml             (minimal Redoc config)
│   ├── scalar-config.ts              (Scalar config with theming)
│   ├── mint-json.md                  (Mintlify mint.json template)
│   ├── github-pages-workflow.yml     (GitHub Actions workflow for docs deployment)
│   ├── makefile-sdk-targets.md       (Makefile targets for SDK regeneration)
│   └── changelog-entry.md            (changelog entry with [BREAKING] annotation)
├── reports/
│   └── README.md                     (how past audit summaries accumulate)
└── research/                         (authored by scripture-historian — DO NOT MODIFY)
    ├── research-plan.md
    ├── research-summary.md
    ├── index.md
    └── external/                     (10 source notes from the normal-depth research pass)

Tool selection at a glance

Renderer	Best for	Hosting	Price
Scalar	New projects, 2026 default, rich theming, interactive console	Self-hosted, Scalar Cloud	Free / Cloud paid
Redoc	Enterprise; proven three-panel layout; Redocly platform	Self-hosted, Redocly	Free (OSS) / Pro
Swagger UI	Widest ecosystem; legacy compatibility	Self-hosted	Free (OSS)
Mintlify	Managed; beautiful defaults; MDX narrative + reference	Managed only	Paid ($150+/mo)
Stoplight	Design-first teams; strong mock server; collaboration	Managed	Paid
Bump.sh	API changelog as primary value; CI diff gate	Managed	Free tier / paid

2026 default recommendation: Scalar for new greenfield projects. See guides/01-tool-selection.md for the full decision tree.

SDK generation at a glance

Tool	Quality	Languages	Price	Notes
openapi-generator-cli	Good (v7+)	50+	Free	Best for Go; Python quality improved
Fern	Excellent	TS, Python, Go, Java	Free OSS; $250/SDK/mo cloud	Acquired by Postman Jan 2026
Speakeasy	Excellent	TS, Python, Go, Java	Free tier; paid	Strong TypeScript quality

See guides/04-sdk-generation.md for generation commands and Makefile targets.

Critical directives (lifted from the Command Brief)

These are non-negotiables. Full justification in guides/00-principles.md.

• Start with the OpenAPI spec, not the tool. Renderer choice is secondary to spec completeness.
• Never recommend a tool without citing concrete trade-offs. Use the comparison matrix in guides/01-tool-selection.md.
• Enrich examples before publishing. Every endpoint needs at least one JSON request example and one response example.
• Break changes must be flagged [BREAKING] in the changelog. No exception.
• Self-hosted setups must include a one-command rebuild. make docs, just docs, or a package.json script.
• Do not scope-creep into general product docs. Route to library-guardian when docs exceed the API reference.

---

Command Brief: ai-tools/command-briefs/api-docs-guardian-command-brief.md Forged by weapon-forge from api-docs-guardian-command-brief.md and research/. Part of the Legion AI Tools Factory by Mario Aldayuz a.k.a @thenotoriousllama.