Importing your OpenAPI spec doesn’t document your API. It builds a skeleton and stops.
An importer writes your Reference docs and quits — no response examples, no error resolutions, and none of the tutorial, how-to, or explanation a developer reaches for when they’re stuck. api-docs-writer imports, then enriches the set, and gates it with five scripts that return PASS or FAIL, not vibes.
For anyone shipping an npm package, an OpenAPI spec, or a client SDK who is tired of docs that look complete and quietly send developers to the wrong place.
opvs-skills install @di-atomic/api-docs-writerThen say: “write API docs for this OpenAPI spec” or “audit these API docs”
Why a generated reference isn’t documentation
import openapi.json → 1 page per tag ✓ looks done (no response example bodies, no error resolutions, and 3 of the 4 kinds of docs a developer reads are never written)
The pages are shaped right and empty inside. And if the spec has no servers block, every code sample points at api.example.com.
import → enrich (examples + errors) → add tutorial / how-to / explanation verify-diataxis-coverage PASS verify-example-per-method PASS verify-error-taxonomy PASS → apply docs theme → publish → deploy
Five scripts gate the set with PASS/FAIL numbers the agent can’t fudge. A doc set that looks complete but fails one does not ship.
A reference is one of four docs. Shipping only that is shipping a quarter.
What you actually get
The whole doc set, not one quadrant
It imports the reference, then writes the tutorial, how-to, and explanation the importer skips — in the calm, precise register technical docs live in. Diátaxis-complete, checked by a script.
Every method earns an example and an error table
One runnable example per method, an error section with resolutions per fallible method — the response bodies and error handling the importer drops. Enforced, not hoped for.
It catches real spec defects
On VayaPin’s live API it flagged a missing servers block that would have aimed every code sample at the wrong host. Render fingerprints keep npmjs, Verdaccio, and GitHub Packages pages from shipping blank.
The two things it checks that a generator won’t
servers block means every sample points at api.example.com. The skill catches it before it ships.A real run — import, enrich, gate, deploy
> write API docs for api.vayapin.app/api/v1/openapi.json
check spec ......... ⚠ no 'servers' block — base URL would be api.example.com
fix ................ add servers: [{ url: 'https://api.vayapin.app' }]
import_openapi ..... API Reference section, one page per tag ✓
enrich ............. + response example bodies, + error tables the importer dropped
add quadrants ...... Tutorial (first call), How-to (common tasks), Explanation
verify-diataxis-coverage ... 4/4 quadrants PASS
verify-example-per-method .. every method has a runnable sample PASS
verify-error-taxonomy ...... every fallible method lists errors PASS
apply docs theme → publish → deploy to docs.vayapin.app
Live — three-column reference, pinned cURL/Python/JS/Go, Try-it + Ask-AI.
Deterministic scripts gate the set — not an LLM grading its own work. That’s why the docs hold up once developers start using them.
I built this by documenting the same stack I ship to clients.
api-docs-writer is one skill in the system behind Di-Atomic — the marketing & compliance agency that runs cognitoAI, SpiderIQ and OPVS. If you want API docs that are complete, example-enforced, and actually live — for your product or your client’s SDK, in any of our seven languages — that’s the day job. Let’s talk.
Book a 30-min call with Di-AtomicJust want the skill? Install @di-atomic/api-docs-writer free.