Hand-written API docs, and the drift they cannot detect
Document a small API by writing the docs, rather than generating a reference from a spec.
A deliberately tiny Rails app whose entire job is five ERB pages: index, quickstart, authentication, endpoints, api reference. No OpenAPI spec, no Redoc, no Slate. The README is the stock Rails placeholder.
The case for it is that a generated reference earns its cost when an API is large, changes often, or has many consumers needing exhaustive parameter tables. This API was small and stable, and what its users needed was a quickstart that got them to a working request. A schema dump has no opinion about where to start.
What it gives up is drift detection. A generated reference is wrong when the spec is wrong; a hand-written one is wrong whenever anyone forgets, and nothing says so. The cheap fix is a contract test in CI that fires the quickstart’s own requests against a live instance and fails when a documented example stops working, catching the drift people notice, without adopting a spec toolchain.
Ships as its own Docker service with bin/docker-entrypoint.
Inferred: the reasoning for skipping OpenAPI is mine. The repo shows the choice, not the argument.