How do you serve the OpenAPI spec for your public API docs?

We run a public REST API and want to add an API reference to our developer portal. Our backend generates the OpenAPI spec from code, and we're trying to decide how to get that spec to the portal.

What we want

- Docs update when the backend changes, without redeploying the frontend

- Docs keep working when the API is down

- Internal endpoints never end up in the public docs

Options we're considering

1. Serve the spec from the API itself, at a path like /xxxx.json. Changes go live with each deploy, but if the API goes down, the docs go down too, and the filtering that hides internal routes has to run at runtime.

2. Publish a static file from CI. On merge, CI generates a public-only spec, uploads it to object storage behind a CDN, and the portal loads it from a fixed URL.

Questions

- Which approach do you use, and has anything bitten you in production?

- Our docs pages are custom-designed. Does your frontend render straight from the OpenAPI spec, or do you first turn it into a simpler JSON for the frontend?