We Automated 60% of Our API Documentation Using AI Coding Tools — Here’s the Exact Workflow
Let’s be honest: nobody enjoys writing API docs. I’ve seen teams burn entire sprints trying to keep READMEs, internal wikis, and Postman collections in sync with a rapidly changing codebase. And more often than not, the docs were already outdated the day they got published.
We set out to fix that. Not by hiring more writers, but by building a documentation pipeline that uses AI coding tools to generate, validate, and publish docs automatically. The result? We reduced manual documentation effort by over 60% across three services. Our devs now spend time fixing real bugs instead of chasing outdated doc strings.
The False Promise of Static Agent Orchestration: Why Your Multi-Agent System Needs a Survival Mode, Not Just a Playbook
The False Promise of Static Agent Orchestration: Why Your Multi-Agent System Needs a Survival Mode, Not Just a… ...
Here’s exactly how we did it — the tools, the prompts, the linters, and the gotchas we hit along the way.
The Problem: Docs That Lie
Our product team relied on our REST API docs to onboard new partners. Every time we added an endpoint, the documentation lagged by at least two weeks. By the time it was updated, half the parameters had changed. Sound familiar?
Outsourcing Software Development in 2025: The CTO’s Playbook for Real Results
TL;DR: Outsourcing software can cut costs by 40-60% and speed up delivery, but only if you pick the… ...
We tried manual reviews. We tried wiki rules. Nothing stuck.
The core issue: documentation is a second-class citizen in most CI pipelines. Code gets tested and linted. Docs get a “we’ll update it later” sticker.
So we flipped the script. We made doc generation a required step in our pull request flow.
The Tech Stack
Here’s what we used:
- Claude Code (via the terminal) – for generating OpenAPI YAML fragments from code
- Node.js + Express – the API services (but works with Python too)
- Spectral – open-source OpenAPI linter
- stoplight/prism – for mocking and validation
- GitHub Actions – to orchestrate the entire pipeline
- Redoc – for rendering beautiful docs from OpenAPI specs
We debated using a dedicated AI code generator like GitHub Copilot, but Claude Code’s ability to read our full context (file tree, existing conventions, comments) gave us better consistency.
The Workflow: Step by Step
Step 1: Annotate Route Handlers with Structured Comment Blocks
We added a lightweight JSDoc-style block to every route handler. This becomes the single source of truth for the AI tool.
typescript
/**
* @api {post} /api/v2/orders Create a new order
* @apiDescription Creates an order with line items and shipping address.
* @apiParam {String} customerId UUID of the customer
* @apiParam {Object[]} items Array of line items
* @apiParam {String} items[].sku Product SKU
* @apiParam {Number} items[].quantity Quantity (min: 1)
* @apiSuccess {String} orderId Generated order UUID
* @apiError (400) ValidationError Missing required fields
* @apiExample {curl} Example:
* curl -X POST https://api.example.com/api/v2/orders \
* -H "Authorization: Bearer $TOKEN" \
* -d '{"customerId":"abc","items":[{"sku":"123","quantity":2}]}'
*/
app.post('/api/v2/orders', async (req, res) => {
// ... handler logic
});That’s it. No extra frameworks. Just a consistent comment block that the AI can parse.
Step 2: Run Claude Code to Generate/Update OpenAPI Spec
In our CI, we added a step that invokes Claude Code with a specific prompt:
> claude "Read all files in /src/routes. For each route handler that has an @api comment block, generate the corresponding OpenAPI 3.0 path object. Output a single file: openapi-generated.yaml. Only add paths that don't already exist in openapi.yaml (the manual base spec). Merge new paths into the base spec, handling conflicts by keeping the existing version."Why not just overwrite the entire spec? Because some paths have hand-crafted details (deprecation notices, rate limiting headers) that we don’t want AI to touch. We treat AI as a contributor, not the sole author.
Here’s a snippet of what Claude Code spits out:
yaml
paths:
/api/v2/orders:
post:
summary: Create a new order
operationId: createOrder
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customerId
- items
properties:
customerId:
type: string
format: uuid
items:
type: array
items:
type: object
properties:
sku:
type: string
quantity:
type: integer
minimum: 1
responses:
'200':
description: Successful order creation
content:
application/json:
schema:
type: object
properties:
orderId:
type: string
format: uuidYou’ll notice the AI preserves the `minimum`, `format`, and `required` constraints from our comments. It’s not perfect — we had to iterate on the prompt twice to get it to respect existing YAML anchors.
Step 3: Lint the Generated Spec with Spectral
Spectral catches inconsistencies fast. We run it on every PR:
bash
spectral lint openapi.yaml --ruleset .spectral/rules.yamlOur ruleset includes checks like “every `POST` must have a request body” and “all parameters must have a description”. If the AI-generated spec fails, the pipeline breaks and the PR doesn’t merge.
This forces the developer to either fix the comment block (so the next AI run is correct) or manually patch the spec.
Step 4: Validate Against a Mock Server
We use Prism to spin up a mock version of the new spec and run a few smoke tests:
bash
prism mock openapi.yaml -p 4010 &
# Then hit the mock endpoints
curl -s http://localhost:4010/api/v2/orders -X POST -d '{"customerId":"bad"}' | jq .If the mock rejects a request that our real API would accept, we know the spec is wrong. This catches 80% of hallucinations.
Step 5: Auto-Publish Docs to Internal Portal
Once the PR is merged, a GitHub Actions workflow builds Redoc from the final `openapi.yaml` and deploys the HTML to our docs portal. No manual intervention.
What We Measured After 3 Months
We tracked documentation completeness before and after the pipeline:
| Metric | Before | After | Change |
|---|---|---|---|
| Endpoints with accurate OpenAPI spec | 34% | 91% | +57 points |
| Average time from code merge to docs publish | 11 days | 4 hours | -96% |
| Developer time spent on docs per sprint | 18 hours | 7 hours | -61% |
The 60% automation claim is real. We still manually tune the spec for edge cases (deprecation notices, custom headers), but the grunt work is gone.
3 Gotchas We Learned the Hard Way
- Context window limits still bite. Claude Code can’t read 500 route files at once. We split the generation into batches by module (orders, users, payments) and merge later.
- AI loves to invent example values. It once generated an example order with a status that didn’t exist in our system. Spectral’s `no-undefined-examples` rule saved us.
- Comment drift happens fast. If a developer updates the route logic but forgets to update the comment block, the AI regenerates based on stale comments. We added a pre-commit hook that warns when the route handler changes but the comment block hasn’t been updated.
Why We Chose AI Over a Dedicated Doc Gen Library
We evaluated tools like `swagger-jsdoc` and `apidoc`. They work, but they require you to write annotations in a rigid format that often breaks under heavy customization. AI coding tools, on the other hand, can infer structure from loose conventions and adapt to our evolving style.
*But don’t let the AI write docs unsupervised.* You need the linter and the mock server as guardrails. Otherwise, you’ll get beautifully formatted nonsense.
The Vietnam Advantage: How Our Remote Team Made This Possible
This pipeline was built by a team of three developers in Ho Chi Minh City and Can Tho. Honestly, we couldn’t have iterated so fast without their deep understanding of both the business logic and the DevOps tooling.
One of our senior engineers in Can Tho suggested using `yq` to merge YAML files instead of writing a custom Node script. That single tip saved us a week of debugging merge conflicts. It’s the kind of pragmatic thinking you get when you hire Vietnamese developers who’ve spent years solving real production problems — not just coding to spec.
If you’re considering a similar automation, don’t underestimate the value of a team that treats infrastructure as code with the same rigor as application logic.
Start Small, Iterate Fast
You don’t need a massive AI orchestration platform to automate documentation. A handful of open-source tools, a solid prompt, and a CI pipeline that enforces quality will get you 80% of the way there.
Try it on a single service first. Run the linter. Fix the hallucinations. Then expand.
Your devs will thank you. And your API consumers will finally get docs that match the actual API.
—
Frequently Asked Questions
Q: How do you prevent the AI from overwriting manually crafted parts of the OpenAPI spec?
A: We keep a base spec file (`openapi.yaml`) with all hand-tuned paths and use Claude Code’s “merge only new paths” prompt. We also run a diff check in the CI to alert if any existing paths are modified without a human review.
Q: What if Claude Code hallucinates an endpoint that doesn’t exist?
A: The mock server validation catches that immediately. If the mock can’t serve a response that matches our production behavior, the PR fails. We’ve also added a regression test that compares mock responses against a snapshot of real API calls.
Q: Does this workflow work for GraphQL or gRPC?
A: We’ve tested it with GraphQL by having Claude Code generate SDL schema updates from resolver annotations. The same principle applies — structured comments → AI generation → linting → validation. For gRPC, you’d need to output `.proto` files instead of OpenAPI YAML.
Q: How much does this cost in terms of AI API calls?
A: For a service with 200 endpoints, Claude Code costs about $0.30 per generation run (we use the Claude 3 Opus model for accuracy, but Sonnet is cheaper). We run it twice per PR (once after code push, once after review changes). Total monthly cost: under $15. The time savings easily justify it.
Related reading: Why You Should Hire Vietnamese Developers in 2025: The Strategic Edge for Tech Leaders
Related reading: Why Vietnam Outsourcing Is the Smartest Decision for Your 2025 Tech Roadmap
