Generating API documentation examples

Kid Circus

1. Explanation order
2. Backwards API docs
3. Annotation styles
4. API docs annotations
5. Annotations in HTML
6. JSON API responses in HTML
7. Generated API examples ←

Despite developers’ wishful thinking, you can’t generate API documentation. You can generate layouts and outlines based on an API, but they don’t actually document the API.

You can, however, generate examples, so you can start documentation with examples. Example-first API docs start with a representative set of API request and response examples, and document them with annotations.

Generate the examples from API calls

To document an existing HTTP API, start with a set of example API calls, and capture each one’s complete HTTP request and response.

cURL gives you plain output that still needs formatting and syntax colouring:

curl --verbose --silent \
 --header 'Accept: application/vnd.nrk.fargerik.palette.2.0+json' \
 https://fargerik-psapi.nrk.no/tv/series/lykkeland 2>&1 | \
 egrep --invert-match '^([ *]|[{}] )' | sed 's/^[<>] //'

This commend line includes several incantations to limit the output to request and response (but still has an untamed * Closing connection 0 on the end):

GET /tv/series/lykkeland HTTP/2
Host: fargerik-psapi.nrk.no
User-Agent: curl/7.64.1
Accept: application/vnd.nrk.fargerik.palette.2.0+json

HTTP/2 200 
content-type: application/vnd.nrk.fargerik.palette.2.0+json; charset=utf-8
request-context: appId=cid-v1:804d17e3-01ed-46af-88ac-f8389a23ccf9
x-robots-tag: noindex, noarchive, nosnippet
access-control-allow-origin: *
cache-control: max-age=3600,stale-while-revalidate=3600,stale-if-error=3600
etag: W/"107-m9HE7qp+5oItcLJVfdhx8ZPSGYk"
date: Mon, 16 Jan 2023 09:46:16 GMT
content-length: 263
alt-svc: h3=":443"; ma=93600
vary: Accept
strict-transport-security: max-age=15768000

{"light":"#affdff","whiteMedium30":"#c1cbcb","whiteDark30":"#bac3c3",
"mediumLight20":"#497475","mediumLight10":"#3d6364","mediumLight5":"#365b5c",
"medium":"#305253","mediumDark40":"#274748","dark":"#1a3737","disabledOnMedium":"#bdcccd",
"disabledOnDark":"#8c9e9e"}* Closing connection 0

HTTPie has a simpler command-line syntax that resembles HTTP more.

http --verbose GET https://fargerik-psapi.nrk.no/tv/series/lykkeland \
 Accept:application/vnd.nrk.fargerik.palette.2.0+json

HTTPie also defaults to friendlier output that automatically formats and colours HTTP and JSON responses:

GET /tv/series/lykkeland HTTP/1.1
Accept: application/vnd.nrk.fargerik.palette.2.0+json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: fargerik-psapi.nrk.no
User-Agent: HTTPie/2.3.0

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: h3=":443"; ma=93600
Cache-Control: max-age=3600,stale-while-revalidate=3600,stale-if-error=3600
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 164
Content-Type: application/vnd.nrk.fargerik.palette.2.0+json; charset=utf-8
Date: Sat, 07 Jan 2023 16:59:30 GMT
ETag: W/"107-m9HE7qp+5oItcLJVfdhx8ZPSGYk"
Strict-Transport-Security: max-age=15768000
Vary: Accept-Encoding
Vary: Accept
X-Robots-Tag: noindex, noarchive, nosnippet
request-context: appId=cid-v1:804d17e3-01ed-46af-88ac-f8389a23ccf9

{
    "dark": "#1a3737",
    "disabledOnDark": "#8c9e9e",
    "disabledOnMedium": "#bdcccd",
    "light": "#affdff",
    "medium": "#305253",
    "mediumDark40": "#274748",
    "mediumLight10": "#3d6364",
    "mediumLight20": "#497475",
    "mediumLight5": "#365b5c",
    "whiteDark30": "#bac3c3",
    "whiteMedium30": "#c1cbcb"
}

If you write documentation by hand, you can just copy-paste this into your documentation, and save the command line somewhere. You could also automate that.

Automate capturing examples

Whether you capture API HTTP requests and responses via command line tools or programmatically, you can automate capturing and saving them as text files. This first automation step already gives you a set of examples that you can update automatically, saving documentation effort. You might also want to use this automation to automate API tests, to check expected responses, while saving the output for use in documentation.

Use version control to identify API changes

When you automatically save API HTTP responses to files, you can use version control to identify changes. Unexpected changes may indicate bugs, and expected changes need documenting. For this to work, you’ll have to suppress response headers whose values change independently of the API, such as the Date header and any correlation IDs.

When you update documentation as part of a docs-as-code approach, using file-based version control, these API output changes make the corresponding API changes explicit. This gives reviewers a reliable way to review documentation changes using developer tools, similarly to how technical writers might review changes in a traditional document management system.

Document changes

Once you have text files for the API HTTP requests and responses you want to document, you can add annotations in HTML. Ideally, you wouldn’t have to copy these requests and responses into the documentation, and could instead include them automatically. This would require a way to specify the annotation locations, such as the base64url-encoded ship ID in the request line (starting with POST) of this pirate crew update:

Unfortunately, this all means yet more custom documentation system implementation. Perhaps all of this explains the CMS problem: we have too many content management systems because people keep inventing new ways to do documentation. And that sounds like front-end frameworks and user-interface designs.