API Docs Weapon

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

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

SDK generation at a glance

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.