Build API Documentation from OpenAPI: Examples, Postman and Response Checks
Turn a reviewed OpenAPI 3.0 JSON contract into a searchable reference and request examples. Check a saved response, preserve undocumented behavior and separate documentation from live API testing.
Fastest way
Ask your AI to do it
Paste this into the AI agent you already use:
Use API Docs Studio to document my reviewed OpenAPI 3.0 JSON contract. Check the supported subset, preserve actual authentication and errors, generate request examples and Postman files, then check a saved sanitized response. Keep undocumented behavior explicit and do not execute requests as part of documentation generation.
Can an agent turn OpenAPI into usable API documentation?
API Docs Studio v1.0.1 generates a searchable HTML reference, Markdown, cURL/Python/Fetch examples and a Postman v2.1 collection from a supported OpenAPI 3.0 JSON contract. Python 3.10+ runs the included tools offline without dependencies or an API key. The studio generates files; it never calls the documented service.
Establish the contract before generating examples
- Read actual routes, tests or the approved contract. Record the API version, fixed HTTPS server, parameter locations, required inputs, authentication and documented error cases. Mark proposed behavior explicitly.
- Read references/input.md. This release accepts OpenAPI 3.0.0–3.0.3 JSON, not arbitrary YAML or OpenAPI 3.1. It supports local references and a bounded schema subset; remote references, recursion and unsupported composition are rejected.
- Use sanitized example bodies and token placeholders. A supplied source hash identifies the bytes used; it does not prove those bytes describe the deployed implementation.
Generate the fictional reference and check a saved response
Install the complete package, read SKILL.md and run from its folder into a new output directory. The first command generates the included fictional Northstar API reference; the second validates the supplied saved response for one operation and status. Neither command sends a request.
Check setup and the current API Docs Studio release
python3 scripts/build-docs.py --spec examples/openapi.json --output ./practice-api --demo
python3 scripts/check-response.py --spec examples/openapi.json --operation getWorkspace --status 200 --response examples/workspace-response.jsonInspect every exported request before using it
- Open practice-api/index.html. Search endpoints, select an operation and switch request languages. Compare parameter placement, URL encoding, authentication placeholders and response statuses with the original contract.
- Download the actual snippets, original OpenAPI, Markdown and Postman collection. Review quality.json and the delivery manifest. Missing error documentation should remain visible as a gap rather than becoming an invented response.
- For an authorized real contract, omit --demo, rebuild and compare saved sanitized responses. A passing subset check does not establish authorization, side effects, business rules, latency or idempotency. Unsupported assertions need their own tests.
Inspect the current example output → — Compare the visible result with the exported files and checks described in this section.
Hand documentation to the implementation owner
Keep the reviewed contract, generated files, warnings and unresolved questions together. Importing a collection is not proof of a successful integration. Live testing is a separate authorized task; review credentials and create/update/delete operations before running examples against a service.