So far on Troyal , my fictional royalty-tracking API, I've written the product brief, the API design tables, the README and a Getting Started guide.

Recently, I wrote the OpenAPI spec.

My API design tables say what each endpoint does, in plain words. An OpenAPI file says the same thing in a standard format that tools can read. Many real API docs sites are generated from files like this.

I built it one endpoint at a time:

GET /works to list works

POST /works to create one

GET , PATCH and DELETE on /works/{id} to retrieve, update or delete a single work

Each endpoint has its request body, its success response and its errors (400, 401, 404 and 429), matching the troubleshooting table in my Getting Started guide.

The most useful lesson was how strict the format is. YAML depends on spacing, and a few stray spaces were enough to break my file. I only caught it because I tested everything in Swagger Editor, which turns the file into a live, readable page.

Everything is public on GitHub.…