D7What it costs the developer
What does this endpoint return?
The honest answer is read the handler. Hand-written OpenAPI is accurate for one afternoon, and nobody is assigned to keep it true.
What actually goes wrong
API documentation written by hand is a second description of the same thing, which makes it a thing that drifts. It is correct on the day it is written and wrong by the end of the sprint.
The cost lands on whoever is integrating: a mobile developer, a client’s team, or you in four months.
What Grit does about it
- The reference is generated from the registered routes and the request and response types, and served at /docs by the API itself.
- Generate a resource, reload the page, and its thirteen routes are there with their parameters and responses.
- It cannot drift, because nobody maintains it.
The commands
Already running
grit start# http://localhost:8080/docs
Every route, in the terminal
grit routes
What it does not do
It documents shape, not meaning. What a status transition implies for your business is prose you still write.