The Brief
Cosmetly needed its API documentation brought up to the standard its product deserved. The existing OpenAPI specification was a monolithic YAML file — functional but increasingly difficult to maintain as the API grew. Adding a new endpoint, updating a schema, or reviewing a change required navigating a single large file with no separation of concerns.
As the lead OpenAPI documentation specialist, I was brought in to refactor the architecture and produce complete, accurate documentation for every endpoint.
What I Built
A full OpenAPI documentation overhaul across two interconnected workstreams:
- Modular YAML Architecture — Broke the monolithic specification into smaller, logically organised files — endpoints, schemas, components, and examples each in their own structure. The refactor preserved all existing API behaviour while making the spec dramatically easier to maintain, review, and extend
- Schema Documentation — Documented every request and response schema with accurate field descriptions, types, constraints, and relationships — working directly against the live staging environment to verify correctness
- Example Data — Added representative example data for every endpoint, giving developers concrete reference points rather than abstract schema definitions
- Bump.sh Integration — The documentation was published via Bump.sh, a modern API documentation platform designed for OpenAPI specs; ensured the modular structure rendered correctly and produced a clean, navigable reference
Approach
OpenAPI documentation work is fundamentally an accuracy problem. A spec that doesn’t match the actual API isn’t documentation — it’s a liability. Every decision in this project was made to close the gap between the spec and the live system.
Working directly in the codebase via Git and GitHub meant the documentation lived alongside the code it described, with the same review process applied to doc changes as to code changes. This is how documentation should work.
The modular architecture follows a clear principle: each file should have a single, obvious responsibility. When an endpoint changes, you know exactly which file to update. When a schema is shared across endpoints, it lives in one place and is referenced, not duplicated.
Results
Cosmetly now has an API reference architecture that can scale with the product — modular, accurate, and built to be maintained by the engineering team without specialist intervention. The complete schema documentation and verified example data give developers everything they need to integrate confidently.