Part 3: I turned my API design into an OpenAPI spec.

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. Next up: the ownership splits and royalty statements, an error codes guide, and a Jira board to track the docs work.

Troyal is fictional. The documentation is real.

https://github.com/joycefoster642/Troyal-API-Docs