Document REST APIs with AI and DocStar

DEV Community

How to Document a REST API with DocStar: Let Your AI Agent Draft It

Documenting a REST API used to mean days of copying routes, parameters and example bodies into a docs tool. With DocStar, your AI coding agent does that part. Connect Claude Code, Cursor or Codex to DocStar, point it at your code, and it documents every endpoint as a draft: method, URL, auth, parameters, a full body example and sample responses. You review, test and publish an interactive API reference, and the same docs also give you a hosted MCP server and a CLI. This guide walks through the agent-first way to document a REST API with DocStar, what good endpoint docs need, and where your review matters most. What good REST API documentation includes Whether a person or an agent writes it, every endpoint needs the same parts. This is the checklist your agent works to, and the one you review against: Part What readers need Purpose One or two sentences on what the endpoint does and when to use it Method and URL GET, POST, PUT, PATCH or DELETE, plus the full path Parameters Query params and path variables, each with a description Authentication How to authorize the call Headers Required headers such as Content-Type Request body A complete, realistic example and what each field means Responses Real success and error examples Try it A way to send the request and see a live response DocStar has a home for each of these in its endpoint editor, and a TRY button on every published endpoint. Step 1: Connect your coding agent to DocStar DocStar runs an MCP server for documentation work. Add it to your agent as a remote MCP server: https://mcp.docstar.io/mcp
Or connect DocStar from your assistant's connector directory if it's listed there. The first time the agent needs your workspace, you sign in to DocStar in your browser. No API key to copy, and the agent only works with the collections your account can access. See Connect Your AI Assistant. Step 2: Ask it to document your API from the code Open the agent in your API's repository and ask in plain words: Use the DocStar MCP. Read our API routes and document every public endpoint in a new DocStar API collection called "Payments API". For each endpoint, write a clear description, every parameter and header, a full JSON body example with every accepted field, and sample success and error responses. The agent reads your routes and finds the auth, parameters, bodies and responses. It shows you the plan, including the collection slug, and waits for your OK. The slug is permanent and becomes part of your MCP URL and CLI commands, so pick something short like your product name. Already have an OpenAPI 3.x, Swagger 2.0 or Postman file? Ask the agent to import it first and then check each endpoint against your code. Our guide to going from OpenAPI to an MCP server shows that flow. Step 3: Review the drafts Everything the agent creates is a draft, so nothing is public yet. Open the collection in DocStar and review it like a pull request. The agent gets the structure right fast; your job is the judgment calls: Names. Action names readers scan for, like Create order or List invoices. Descriptions. Not "The order ID", but "ID of the order, returned by Create order. Starts with ord_." The same words are what AI assistants read when they call your API through your MCP server, so clear descriptions pay off twice. Body fields. Switch the body from Raw to Body Description to see a description box for every JSON field. Check units and formats (cents or dollars, ISO 8601 dates) and which fields are optional. What stays private. Internal or test-only endpoints can simply stay unpublished. Secrets. Tokens and keys belong in environment variables, never in URLs or examples. Want a change? Ask the agent ("make every description say when to use the endpoint") or edit directly. DocStar's editor is real-time and collaborative, so a writer and an engineer can work on the same page at once. Step 4: Test every endpoint against the real API Every endpoint in DocStar is also a working request, so you can check th...

Powered by Readybot.io