OpenAPI

When the project has no API docs

A service with no /docs.json and no openApi { } block is not doing anything wrong, and turning documentation on is not a silent side effect of adding one endpoint: it publishes a specification of every route, including ones nobody meant to advertise, and it adds a compiler plugin to the build.

Offer it once. Say what it adds — the plugin configuration, the two routes, and whether the reference should be exposed publicly or behind the same auth as everything else — and wait. That last question matters more than it sounds: /scalar on a public listener is a map of your API for anyone who asks.

Where docs are already generated some other way — a hand-written openapi.yaml, a gateway that owns the spec — write to that instead of standing up a second source. Two specifications that disagree are worse than one that is out of date.

Ktor generates it; you do not annotate it

Ktor's compiler plugin builds the specification from the routes themselves — the path, the method, the type passed to call.respond, the type read by call.receive — and enriches it from a KDoc comment above the handler.