# What to Look For in API Documentation Tools — Routebase

> Nine criteria that decide whether a documentation tool still fits in two years, written as questions to ask rather than as a list of vendors.

Canonical page: https://routebase.dev/guides/api-documentation/api-documentation-tools/
Chapter 10 of 10 · API Documentation · Last reviewed 2026-09-13 · The Routebase Team

Comparison articles about documentation tools usually list vendors and score them on features. This chapter does something narrower. It names the criteria that still matter after the trial, as questions you can put to any tool including the one you already use.

## The criteria, and why each one is on the list

### 1. Where does the reference come from

Ask whether the endpoint reference is generated from your contract, and then ask the sharper question, which is what happens when the contract changes.

There are three behaviours and they age very differently. A tool that imports a contract once gives you a reference that starts drifting immediately. A tool that renders whatever the contract says right now will publish unreleased work to your consumers. A tool that pins to a released version and tells you a newer one exists keeps the update a decision. The [keeping it up to date](/guides/api-documentation/keeping-api-documentation-up-to-date/) chapter covers why the third behaviour is the one to look for.

### 2. Are documentation versions independent of API versions

Two failures come from getting this wrong, and most tools have exactly one of them.

If documentation can only change when the API does, a typo waits for a release. If documentation always shows the newest content, a consumer still on an older contract reads a page that describes an API they are not calling.

Ask whether you can publish a documentation change without an API release, and whether a reader can reach the documentation for the version they are on.

### 3. Who is allowed to edit a page

This decides where your documentation improvements come from, and the answer is rarely the one on the pricing page.

If editing requires a pull request, your contributors are the people who already write code, and a support engineer who spotted a wrong sentence will not be one of them. If editing only happens in a browser editor, the change that a code review would have prompted never gets prompted.

The arrangement worth asking for is both, which means an editor for the people who write prose and a round trip to files for the people who work in a repository. The [docs as code](/guides/api-documentation/api-docs-as-code/) chapter covers what that bridge costs.

### 4. What can a reader's agent read

More of your readers now arrive with an assistant in the loop, and this criterion is cheap to check and rarely answered on a feature page.

Fetch the tool's own documentation site and look for an index at `/llms.txt` and a Markdown version of a page. Then check the part that usually fails, which is whether the generated endpoint pages are available as text or only as a rendered widget. A site where the guides are readable and the reference is a blank has solved the easy half.

### 5. Where does it live, and is the address yours

Ask three things about hosting. Can you serve on your own domain, is the certificate handled for you, and what happens to that domain if your plan changes.

The address matters beyond appearance. Every link and every search result your documentation earns accrues to the host it is on, so documentation on a vendor domain is an asset you are building for somebody else.

### 6. Can you control who reads it

Most teams need both an internal and a public audience eventually, sometimes for the same API.

Ask whether visibility is a property of a version rather than of the whole site, whether a new version is private by default, and whether you can take a published version back without deleting it. The last one is the difference between a mistake and an incident.

### 7. Does it tell you what readers could not find

A documentation tool that reports page views is reporting traffic. The signal you can act on is the search that returned nothing, followed by feedback attached to a specific page.

Ask whether failed searches are recorded and exposed, because that list is the closest thing to a backlog that writes itself. The [measuring documentation](/guides/api-documentation/measuring-api-documentation/) chapter covers what to do with it.

### 8. What comes out if you leave

Ask what the export contains, in what format, and whether it round-trips.

The weak version of this promise is a dump you cannot import anywhere. The useful version is your pages as Markdown with their structure intact, plus your contract in its original form. Ask while you still have leverage, which is before you sign.

### 9. What exactly is metered

Two questions catch most of the surprises, and both are about the meter rather than the headline price.

Ask what is counted, since seats, projects, hosted sites, page views and custom domains are all used as meters and they reward very different behaviour. Then ask what happens when you cross the line, because a plan that stops serving your documentation is a different risk from one that sends an invoice.

## A scorecard you can use

| Criterion | Question | Weight it if |
|---|---|---|
| Reference source | Generated from the contract, and pinned to a released version | Your contract changes more than rarely |
| Version independence | Can docs change without an API release, and the reverse | You have external consumers |
| Contribution model | Editor for writers, round trip to files for engineers | More than one kind of person writes |
| Agent readability | Index, Markdown per page, reference pages as text | Your readers arrive with assistants |
| Hosting | Your own domain, handled certificate | The documentation is public |
| Access control | Visibility per version, private by default, retractable | You document anything internal |
| Reader signals | Failed searches and per-page feedback | You intend to improve the docs |
| Export | Pages and contract, in a format that round-trips | Always |
| Pricing shape | What is metered, and what happens at the limit | Your traffic or your team will grow |

## How to actually evaluate

Two exercises tell you more than any feature grid.

**Publish one real API.** Not the pet store sample. Take an API with real authentication, a deprecated field and at least one endpoint whose behaviour needs explaining, and get it published in each candidate.

**Then change the contract.** Add a required field, deprecate something, release it, and watch what the tool does. Whether the reference follows silently, refuses to follow, or asks you is the single behaviour that determines how true your documentation will be in six months.

## In Routebase

Routebase was built around the first two criteria. The reference is a pinned snapshot of a published specification version, so it never shows unreleased work and never drifts quietly, and an update banner tells you when a newer release is available. Documentation versions run on their own lifecycle with one live at a time, so prose can be corrected without an API release and a reader on an older contract still has a version that matches.

The rest sits in the same workspace. Pages are written in an editor and can be pulled into Markdown files and pushed back through the CLI, so both kinds of contributor have a way in. Every build emits the machine-readable files an agent reads, including generated Markdown for endpoint pages. Portals run on a Routebase subdomain or on your own domain with an issued certificate. Published versions carry an internal or public flag and can be retracted, and the analytics panel reports the searches that returned nothing. Specifications export as OpenAPI 3.0, 3.1 or 3.2 in YAML or JSON, and documentation pages come out as Markdown.

If you are weighing Routebase against a specific tool, the comparison pages carry the row-by-row detail, including the rows where we do not win. Start with [ReadMe](/readme-alternative/), [Mintlify](/mintlify-alternative/), [Swagger](/swagger-alternative/) or [Stoplight](/stoplight-alternative/), or see what the portal covers on the [API documentation page](/api-documentation/).

## Frequently asked questions

### What should you look for in an API documentation tool?

Ask where the reference comes from, whether documentation versions are independent of contract versions, who on your team is able to edit a page, and what a reader's agent can read. Then ask what comes out if you leave. Those decide whether the tool still fits after the first release, while the features that demo well tend to matter only on the first afternoon.

### Do I need a documentation tool if I have OpenAPI?

A contract gives you a reference, and a reference is one of the three layers readers need. What it does not give you is the guides, the concept pages, the hosting, the search and the version switcher, which is the work a documentation tool is actually doing. A renderer pointed at a file covers the first part of that and none of the rest.

### Should documentation live in the same tool as the API design?

It removes the step where somebody exports a contract and imports it somewhere else, which is the step that gets skipped under deadline. The trade-off is that you are choosing one vendor for two jobs, so it is worth checking that the documentation half would stand on its own if you only needed that.

### How do you compare documentation tools fairly?

Publish one real API in each candidate, including the authentication and at least one deprecated field, and then change the contract and watch what the tool does. A feature list rewards whoever wrote the longest one, while a release cycle shows you which tool will still be telling the truth in six months.

---

[Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.