# How to Write API Reference Documentation — Routebase > Summaries against descriptions, the questions a description has to answer, examples per response, enum values with meaning, and errors a reader can act on. Canonical page: https://routebase.dev/guides/api-documentation/how-to-write-api-documentation/ Chapter 2 of 10 · API Documentation · Last reviewed 2026-09-13 · The Routebase Team The reference is the layer a generator can build for you, and that is exactly why the writing in it matters. The structure arrives for free, so what is left is the part that carries meaning. ## The schema already says the shape Look at what a reader gets from the contract without any prose. They get the path, the method, every parameter with its type, the request body, the response codes and the shape of each body. That is the mechanics, and it is complete. What the reader still does not know is what the operation means in your system, what it changes, what they need to have done first, and what will bite them. Everything you write in the reference should be aimed at that gap. Prose that repeats the type of a field is filler that pushes the useful sentence below the fold. ## Summary and description do different jobs A summary is one line, and it appears in navigation, in search results and in the collapsed list of an endpoint group. Keep it a verb phrase that names the operation, such as `Create an order`, and keep it under about ten words so it does not get truncated somewhere you are not looking. The description is the body. It carries the rules, the side effects, the preconditions and the warnings, and it is the only place where your API can explain itself. ## What a description has to answer Four questions cover almost every endpoint. **What does this do in my domain?** Not `creates an Order resource`, but what actually happens, including anything the caller is now committed to. **What changes on the server?** Name the side effects a reader cannot see, such as an email that goes out, a webhook that fires, or an inventory reservation that expires after a while. **What must be true before calling it?** Preconditions, required permissions, and any ordering constraint between this operation and another. **What goes wrong here specifically?** Not the generic error table, but the failure this endpoint produces that surprises people. A description that answers those is usually three to six sentences, and it is worth more than three pages of restated types. ## Examples per response, not per endpoint One example body at the top of an endpoint is the norm and it is rarely enough, because the interesting cases are the ones that are not the happy path. Give each documented response its own example. The `200` shows a realistic object with plausible values, the `422` shows what a validation failure actually looks like, and the `409` shows the conflict shape. Readers write their error handling against those bodies, so a missing one means somebody is guessing. Values matter more than people expect. An example full of `string` and `0` is structurally correct and teaches nothing, while an example with a real-looking identifier, a real currency code and a plausible timestamp answers three questions at once. ## Enums need meanings and a growth rule A list of allowed values tells a reader what will be accepted. It does not tell them what to expect back or what to do with it. Document each value with its meaning, and where the values form a lifecycle, say which transitions exist. A consumer building a state machine against your `status` field will otherwise infer one from the values they happen to observe. Then say what happens when the list grows. If you may add a value in a future release, say so plainly, because that sentence is what allows a careful consumer to write a tolerant reader instead of a switch statement that throws. ## Errors that leave the reader somewhere The endpoint-level error documentation is where the reader arrives under pressure, which is the strongest argument for putting effort into it. Every documented failure wants three things, meaning the condition that caused it, the application-level code that identifies it, and the next step. Where the next step is a different call, link it. Where the next step is a change of input, name the field. ## Descriptions are read by machines too Everything above serves a human reader, and one property serves a second audience for free. A description that states the domain meaning, the side effects and the preconditions is also what an agent needs in order to choose an operation correctly, because the agent has the schema and nothing else. Vague summaries are the single most common reason an agent calls the wrong endpoint. Our post on [API descriptions that language models can use](/blog/api-descriptions-llms-can-use/) goes into what that changes about how you word them. ## In Routebase The reference in Routebase is rendered from the specification, so summaries, descriptions, parameters, examples and error responses come from the contract and cannot disagree with it. The description editor is a rich editor rather than a plain text box, so a warning about idempotency renders as a callout and a token flow renders as a diagram in the published reference. _Screenshot: Endpoint descriptions are written in the same editor as the guide pages, so a precondition can be a callout and a flow can be a diagram rather than a paragraph._ Where a note belongs to the documentation rather than to the contract, each endpoint in an embedded reference carries its own notes field, so a portal-side annotation does not change the specification other teams consume. The [Endpoints guide](https://docs.routebase.dev/endpoints/) covers the description fields, and [Responses](https://docs.routebase.dev/responses/) covers examples per status code. ## Frequently asked questions ### How do you write a good API endpoint description? Answer the four questions the schema cannot answer. Say what the operation does in business terms, what it changes on the server, and what the caller has to know before calling it. Then say what goes wrong here specifically rather than repeating the generic error table. A description that restates the endpoint name has cost the reader a click and told them nothing. ### What is the difference between a summary and a description? The summary is one short line that identifies the operation in a list, so it works best as a verb phrase such as Create an order. The description is the prose under the title, where the rules, the side effects and the caveats live. Tooling shows them in different places, which is why a long summary looks broken in navigation and a one-word description looks empty on the page. ### Should API examples be generated or written by hand? Generate the shape and write the values. A generated example is always structurally correct and always full of placeholder text that teaches nothing, while a hand-written example is meaningful and slowly goes out of date. Writing realistic values into the contract itself gives you both, because the example travels with the schema and is regenerated with it. ### How do you document enum values? List the values and say what each one means, since the list alone only tells a reader what is allowed rather than what to expect. Where values represent a lifecycle, say which transitions are possible, because a consumer writing a state machine against your status field will otherwise guess. Also say what happens when you add a value later, which is the question every tolerant reader needs answered. --- [Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.