OpenAPI generation for an application's API

An application’s HTTP API is not written by hand, so its reference is not either. Each operation the application exposes is projected into a validated description, and a generator turns those into OpenAPI documents: one for the public API, one for the administration API, each serialised both ways. The output is meant to read like a reference a developer wrote, not like a dump.

The problem it solves

Generated API documentation has a reputation, and it is deserved. The usual output is technically complete and unusable: operations named after internal handlers, every request body inlined so the same shape appears forty times under forty names, authentication described nowhere, error responses absent, and defaults captured from whatever the machine that generated it happened to hold. A developer reading it cannot tell which of six similar endpoints they want, and a generated client built from it has method names nobody would type.

The alternative, writing the reference by hand, fails differently. It is correct on the day it is written and then diverges from the API silently, because nothing compares the two.

What it does

The application’s API description is generated from what the application declares, and committed — reviewable in a diff and servable with no generation step.

The projection comes first: each exposed operation becomes a description carrying its resource, its variant, its address, its authentication mode and its schemas, and that projection is validated before the generator sees it, so every step downstream can assume a well-formed input. The generator itself is a pure step, with no reading or writing of its own, which is what makes it testable in isolation.

Operation names are BUILT rather than borrowed — a verb, the resource noun, then qualifiers, in consistent casing, with a semantic qualifier added for an operation reachable at more than one address so that two paths onto the same operation do not collide. That name becomes the method name of a generated client, which is why it is worth composing carefully.

Structured request and response bodies are hoisted into named components and referenced, and identical shapes are detected by a key-sorted comparison, so the same body authored on different operations collapses onto one component rather than repeating. Bare scalars stay inline, because a reference to a one-line schema is pure overhead.

Security schemes are emitted unconditionally, because every Wildo API authenticates the same three ways, and each operation references the ones that apply rather than describing them again. The error responses the framework owns are written once and referenced from every operation that can return them.

A section with no operations after filtering is omitted rather than emitted empty.

Limits

It describes the API the application declares. An endpoint added outside the resource system is outside the projection and therefore outside the document.

The conservation check is a consumer-side comparison between the rendered navigation and the generated documents, so it proves the reference represents every generated operation once. It does not compare either against a running server.

The generator produces the document; serialising it to either format is a separate step — which is why the same document appears twice on disk rather than once.