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 /worksto list worksPOST /worksto create oneGET,PATCHandDELETEon/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.
About the author
- Technical writer with Legal background.
Comments
Join the discussionEverything is coming together perfectly! Love this!❤️🥹🥳😍🌸🎈🩷🎂🎊🌸
Introducing: Troyal.
I'm a technical writer building a fictional product called Troyal, an API for tracking music and film royalties, and writing the documentation for it from scratch. This series follows each step as I go, from the first idea to the finished docs, including the messy parts.
