How to Create Interactive API Documentation

With DocStar, every endpoint you publish becomes interactive API documentation: readers click TRY to send a real request from the docs, see the live response, copy a ready-made code snippet and fill in their own API key from a variables panel. And you don't have to build those pages by hand. Connect your coding agent to the DocStar MCP, ask it to document your API, and it drafts every endpoint with request examples, field descriptions and sample responses for you to review and publish.

Interactive docs matter because developers judge an API in the first few minutes. If they can make a successful call from the docs page, before writing any code, they keep going. If they have to copy a URL into another tool, guess the auth header and work out the body, many stop. This guide shows how to get there with DocStar, with your AI agent doing the heavy lifting.

What makes API documentation "interactive"

Static API docs describe a request. Interactive API docs let the reader run it. In practice that means four things on every endpoint page:

The quality of all four depends on the same thing: complete, accurate endpoint docs. A TRY button on an endpoint with a wrong field name just produces a faster error. That is why the main work is documenting the endpoints well, and that is the part your AI agent is best at.

How to create interactive API docs in DocStar with your AI agent

DocStar is built agent-first. Instead of filling in endpoint forms one by one, you connect Claude Code, Cursor, Codex or another assistant to DocStar and describe what you want. The agent reads your code, writes the docs and saves them as drafts. You review and publish.

Step 1: Connect your agent to DocStar

Add DocStar to your assistant from its connector directory if it's listed there. If it isn't, add it as a custom (remote) MCP server with this URL:

https://mcp.docstar.io/mcp

The first time the assistant needs your workspace, you sign in to DocStar in your browser. There is no API key to copy, and the assistant only sees the workspaces and collections your account can access, with your permissions. Full steps are in Connect Your AI Assistant.

Step 2: Give it one prompt

Open your API project in the assistant and paste something like this:

Read the routes in this repo and document every public endpoint in a new DocStar API collection called "Payments API". For each endpoint, use the full URL (not a placeholder), describe what it does and how it authenticates, document every header, query param and path variable, add a complete JSON request body example with a description for each field, and add sample responses for success and the common errors (400, 401, 404). Group endpoints into modules with a short description each. Save everything as drafts and show me the plan before you create anything.

Step 3: Let the agent do the work

Here is what happens next:

1. It reads your code. The agent walks your routes, controllers and validation schemas to find each endpoint, its method, parameters and body.

2. It shows you a plan. You see the collection, the modules and the endpoints it intends to create. DocStar's MCP asks before it creates, changes or publishes anything.

3. It writes the endpoints. Each endpoint gets a name, URL, description, headers, params, a full request body example, per-field descriptions and sample responses.

4. It saves drafts. Nothing reaches your live docs until it's published.

If you already have an OpenAPI 3.x, Swagger 2.0 or Postman file, the agent can start from it instead: DocStar imports all three, and the agent then fills in the gaps (missing descriptions, sample responses, field notes) from your code. For a deeper walkthrough of this part, see How to Document a REST API.

Step 4: Review like an editor, not a typist

Your job is judgment, not data entry. Read through the drafts and check:

• What stays private. Internal or admin endpoints the agent found but shouldn't be public.

• Naming and tone. Endpoint names that match how your users talk ("Create payment", not "postPaymentV2Handler").

• Secrets. Example values must be fake. DocStar also warns you if it finds sensitive values when you publish an endpoint.

• Responses. Sample responses should match what the API really returns today.

You can test any endpoint from the editor while reviewing: click Send and check the real response. DocStar sends most requests through its own server, so you don't hit browser CORS limits, and requests to localhost go straight from your browser so you can test an API running on your machine. A good live response can be saved with Add to Sample Response. More in Send and Test Requests.

Step 5: Share a public environment

This is the step that turns a reference into a playground, and it's one a person should do, because it decides what readers can see. In your API collection, open Settings → Public Environment, pick an environment and choose which variables to share:

• Share the base URL and harmless defaults so TRY works on the first click.

• Leave the API key empty and mark it Editable, so each reader enters their own.

• Never publish real secrets. Published values are visible to anyone who can read your docs.

Readers then see a Variables panel on endpoint pages and use it when they click TRY. Details are in Environments and Variables.

Step 6: Publish

When you're happy, tell the agent "publish the Payments API collection", or publish from the app. Every published endpoint now has the TRY button, code snippets and your sample responses.

One set of docs, four interactive surfaces

Interactive docs in DocStar don't stop at the browser. The same published endpoints power:

• Your docs site, with TRY, variables and code snippets for human readers.

• llms.txt and Markdown copies, so AI assistants can read your reference.

• Your collection's MCP server, so assistants like Claude, ChatGPT and Cursor can search your docs and call your API, with users signing in with their own account where you set that up.

• The DocStar CLI, which turns published API docs into terminal commands. See How to Generate a CLI from Your OpenAPI Spec.

So the effort you put into a clear request body example or an accurate sample response pays off four times. It also raises the stakes: when docs are wrong, an agent calling your API through the MCP server uses the wrong field and the call fails.

Keep it current

Interactive docs go stale faster than you'd think. Someone renames a field, and the TRY button starts returning 400s. Two ways to keep up, both agent-first:

Ask your agent in the same change. When you change an endpoint, add one line to the prompt: "and update its DocStar endpoint docs to match, as a draft." The agent reads the existing page, edits it and shows you the change.

Put the docs next to the code with GitHub Sync. With GitHub Sync, your OpenAPI files live in the repo (in api-docs/) and change in the same pull request as the code. A docstar.md file plus one line in AGENTS.md tells your coding agent to update the spec whenever an endpoint changes, the GitHub Action publishes changed files to DocStar on push, and spec changes show up in the PR diff for review. You don't even have to set it up yourself: with the DocStar MCP connected, ask "set up DocStar GitHub Sync for this repo" and the agent does it.

To be clear about the limit: GitHub Sync works when the agent (or a developer) updates the spec. DocStar doesn't watch your repo or detect drift on its own. We cover the whole workflow in How to Keep Your API Docs in Sync with Your Code.

Tips for interactive docs developers actually use

• Lead with a working first call. Make your simplest, safest endpoint (like "Get current user") the first one, and pair it with a short getting started guide.

• Use full URLs. A request URL that reads https://api.example.com/v1/payments works for people, the CLI and AI agents alike.

• Document errors, not just success. A 401 sample with "check your API key header" saves a support ticket.

• Describe every body field. Type, whether it's required and an example value. This is what AI agents rely on most.

• Keep TRY safe. Point the public environment at a sandbox or test mode if your API has one.

Prefer to click?

You can build everything by hand too. In an API collection, click Add Page → Endpoint, fill in the method and URL, then use the Params, Authorization, Headers and Body tabs. Switch a raw JSON body to Body Description to describe each field, click Send and Add to Sample Response to save real responses, then publish. It works well for a handful of endpoints; for a whole API, the agent is much faster.

Why teams choose DocStar for interactive API docs

• Agent-first from day one. Your coding agent writes the endpoint docs from your code; you review and publish.

• Interactive by default. TRY, code snippets and a public environment on every published endpoint, with no extra setup.

• Safe by design. The agent asks before changing anything, edits are drafts until published, and DocStar warns about sensitive values.

• Built for AI, not just people. The same docs feed your MCP server, CLI and llms.txt.

• Everything in one workspace. API reference, guides, help center, changelog and blog share one editor, one team and one brand.

FAQ

Can readers try API requests without signing in to DocStar? Yes. Readers of your published API reference click TRY on an endpoint page and see the live response. Share a public environment so they start with the right base URL, and leave key fields editable so they enter their own API key.

Will my API key be exposed in the docs? Only if you publish it. Public environment values are visible to anyone who can read your docs, so leave secrets empty and mark them Editable. DocStar also warns you if it finds sensitive values when you publish an endpoint.

Can my AI agent create the sample responses? Yes. Through the DocStar MCP, your agent can create endpoint docs with requests and responses from your code. Check them against real responses before publishing; you can test any endpoint from the editor and save the live response with Add to Sample Response.

I already have an OpenAPI file. Do I need to start over? No. DocStar imports OpenAPI 3.x, Swagger 2.0 and Postman collections. Import it, then ask your agent to fill in missing descriptions, field notes and sample responses.

Which languages do the code snippets cover? Shell (cURL), Node, Python, Java, Go and PHP, among others. Readers pick a language and copy the code for the request.

Get started free

Connect your coding agent to DocStar, give it one prompt and have interactive API docs live today. Get started free.

Originally published on the DocStar blog. Try DocStar free: https://docstar.io