Skip to main content

Trends, tech news, and tool comparisons.

How to write docs for a SaaS API: a four-part structure that works

· 7 min read
Dealpuffin
Proof points and live coupons for early adopters

To write docs for a SaaS API, split them into four parts: a reference generated from an OpenAPI file, a quickstart that gets a first call working, a handful of how-to guides for real tasks, and a short explanation page for concepts such as auth and rate limits. Keep each part to one job. Most weak API docs fail because one page tries to be all four.

This post uses two primary sources, the Diátaxis documentation framework and the OpenAPI Initiative's introduction, both read on 15 November 2026. Suggestions that come from us rather than those sources are marked.

Why four parts instead of one long page​

Diátaxis identifies four needs and four matching forms of documentation: tutorials, how-to guides, technical reference and explanation. Its point is that these serve different readers in different moments, so mixing them hurts all of them.

For an API this maps cleanly:

Reader's questionDiátaxis formWhat it looks like for your API
"Can I make this work at all?"TutorialA quickstart ending in a first successful call
"How do I do X?"How-to guide"How to issue a refund", "How to paginate results"
"What exactly does this endpoint accept?"ReferenceEndpoint, parameter and error listings
"Why does it work this way?"ExplanationAuth model, idempotency, rate limits

Step 1: Write an OpenAPI description first​

An OpenAPI Description is a machine-readable specification of an HTTP API. The OpenAPI introduction says reference documentation can be generated from it as a step in the build process, which prevents out-of-sync docs. It adds that the same file can drive generated client code and mock servers built from the examples you include. The specification is vendor-neutral and maintained by the OpenAPI Initiative under the Linux Foundation.

A minimal file looks like this:

openapi: 3.1.0
info:
title: Example API
version: 2026-11-15
paths:
/invoices/{id}:
get:
summary: Retrieve an invoice
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The invoice

If your framework can generate the file from your code, use that. If it cannot, write it by hand and add a CI check that your tests exercise every path in it. Our suggestion: treat a mismatch between the file and the live API as a failing build.

Step 2: Generate the reference, and keep it austere​

Diátaxis says the only purpose of reference is to describe as succinctly and orderly as possible, and that it should be neutral. It also notes that API documentation can be generated from the software it describes, which keeps it accurate to the code.

So do not hand-edit reference pages. Put your effort into the fields the generator cannot invent: a one-line summary per endpoint, a description for each parameter, a realistic example request and response, and every error code with its cause. Link out to how-to guides instead of explaining inside the reference.

Step 3: Write one quickstart​

A quickstart is the tutorial. It should take a new developer from nothing to one working call, and nothing more. Our suggested shape:

  1. How to get an API key, in one paragraph.
  2. One copy-paste request with the key in an environment variable.
  3. The response the reader should see, shown in full.
  4. Three links: the reference, your top how-to guides and the explanation page on auth.

Test it by giving the page to someone who has never seen your product and watching where they stall. Stalls show you what the page is missing. This is the same logic as running a beta program for a new SaaS: you learn more from watching one person than from guessing.

Step 4: Add how-to guides from real questions​

Diátaxis describes how-to guides as goal-oriented directions that must be written from the perspective of the user, not the machinery. Its naming advice is practical: titles should say exactly what the guide shows, so "How to integrate application performance monitoring" is better than "Application performance monitoring". It adds that search engines appreciate good titles as much as people do.

Our suggestion is to pick topics from evidence: start with the five questions your support inbox gets most often. For a billing API that might be "how to retry a failed charge", "how to verify a webhook" and "how to filter by date range". For a worked example of a task-first guide, see how to test Stripe webhooks locally.

Keep each guide to one goal. Diátaxis warns against polluting a how-to with every possible thing related to the topic, and says to link to reference instead.

Step 5: Write one explanation page​

Explanation answers "why". Cover the choices a developer cannot see from the endpoints: how authentication works, whether requests can be retried safely, what your rate limits are and what happens when someone hits them, and how you version the API. Only state limits you have verified in your own code or config.

If you also publish an MCP server, say how it relates to the REST API, because developers will ask. MCP server vs REST API for a SaaS covers that choice.

Step 6: Publish changes and deprecations​

Docs are accurate only on the day you publish them. Add a changelog and put deprecations in it with dates. Setting up a changelog takes an afternoon and gives integrators somewhere to look before something breaks.

A launch-week checklist​

  • The OpenAPI file validates and is the source of the reference.
  • Every endpoint has a summary, parameter descriptions, an example and its error codes.
  • A new developer can make a first call from the quickstart in one sitting.
  • At least three how-to guides exist, titled by the task.
  • Auth, retries, rate limits and versioning are on one explanation page.
  • A changelog exists, even if it has one entry.
  • Every page has a visible way to report a mistake, such as an email address or an issue link.

Frequently asked questions​

Do I need OpenAPI to document an API?​

No, but it helps. The OpenAPI introduction says a machine-readable description lets you generate reference docs, client code and mock servers, and it reduces drift between docs and behavior. You can still write docs by hand for a very small API.

What should an API quickstart include?​

A way to get credentials, one working request, the expected response and links to what comes next. Keep it to a single path from nothing to a first successful call.

How long should API docs be?​

As long as each page's single job needs. Diátaxis suggests separating tutorials, how-to guides, reference and explanation instead of capping length, so a reference page can be long while a how-to guide stays short.

Should I write docs before or after the API?​

Writing the OpenAPI description first is a cheap way to review the design before building it, and the introduction notes that examples in the file can power mock servers for early testing.