The docs portal

A documentation site served by the gateway itself, rendered from the same compiled document the gateway is enforcing.

That is the whole idea. Documentation generated from a copy of the spec can disagree with the spec being enforced; documentation generated from the enforced object cannot. Every page carries the version and content digest in force, so a reader always knows which contract they are reading.

Turn it on in the gateway's config:

# apip.ymlportal: true

Off - the default - there is no /docs route at all. A request to /docs is handled like any other path your document does not declare: forwarded, and counted undeclared.

What is on it

• The generated reference: every operation, its parameters, its request and response schemas, with a console for sending one.
• Your prose guides, written in the console and folded in beside the reference. Getting-started pages, authentication notes, migration advice - the things a generated reference cannot say.
• Per-operation client snippets.
• Search, over both.

Guides are written on the proxy's Docs tab and reach the portal on the gateway's next registry poll.

The reality badge

Optional, and off until you say otherwise: an operation whose responses have actually drifted from their schema can say so, on the page that documents it.

It is the most honest thing in the product and the most uncomfortable, which is why it is opt-in per proxy. Some teams want their public documentation to admit that GET /orders has been returning a nullable field it does not declare; some very much do not. Off, no badge is rendered anywhere and the portal's data endpoint reports nothing.

The badge is filled from the gateway's own drift aggregates - the same ones it ships to us - so what the badge says and what your drift report says reconcile by construction rather than by us keeping two things in step.

It costs nothing per request

Every page is rendered once, when the gateway compiles the spec, which happens off the request path. A request into /docs is a lookup into pre-rendered bytes.

That matters because this is the same process serving your API. A documentation site that reflowed markdown on every hit would be a documentation site quietly competing with your traffic for the same loop.