Public API docs generated safely from source

TL;DR

• The API needed documentation that stayed close to the code without exposing private routes.
• I needed a public contract that could be generated from the internal one.
• I filtered the API surface before generating docs and runnable request collections.
• The result was documentation that could move with the code while keeping internal endpoints out of sight.

API documentation is most useful when it is close to the code that defines the API. It is also risky when internal routes leak into public references.

Where it started

The complete API contract included routes that were useful internally but not appropriate for public documentation. Hand-maintained docs would drift, but raw generated docs would reveal too much.

What needed to change

The pipeline separates the complete internal contract from the public contract. Public documentation is generated from an allowlisted surface instead of a hand-maintained document.

That keeps the docs useful while reducing the chance that private routes, admin workflows, or incomplete operations appear outside the team.

What I built

The API contract is filtered before it reaches the documentation step. The same filtered contract can produce static docs and request collections that developers can run locally.

Examples stay aligned with the route definitions because they come from the same source.

What changed

Documentation becomes part of the system, not a side task. When the contract changes, the docs can change with it.

What I would watch

Filtering needs clear rules. If the public surface is not explicit, the generated docs can become either too sparse to help or too generous to be safe.