| 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:
guides/00-principles.md — the spec-first mindset, the five quality gates, when to route elsewhere, and the core invariants.guides/01-tool-selection.md — the full tool comparison matrix and decision tree. Read this before recommending any renderer.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.
