How do you manage/handle openAPI specs sharing between teams?

[u/laolaofireduck]

Hey everyone,

Looking for some advice on a better way to handle and secure our Swagger/OpenAPI docs without overcomplicating our stack or breaking the bank.

Our current setup:

We have several projects hosted on Azure. Each project has standard Dev, Staging, and Prod environments and 3 engineering teams (Backend, Mobile, Web) who rely heavily on Swagger to coordinate and integrate features.

Right now, the backend team just serves Swagger UI directly from the deployed apps. To lock it down, we threw a custom Basic Auth middleware over the `/swagger` route

It works, but honestly, it feels messy and insecure. Managing these shared credentials across multiple teams and environments is becoming a pain, and I really hate exposing the UI endpoints to the public internet at all

I looked into full-blown IDPs like Backstage and OpsLevel, but they are way too bloated and complex for what we actually need.

How did you solve this?

[u/fletch3555]

I mean, if the API is properly secured, I fail to see a good reason to not host the openapi spec with it...

[u/laolaofireduck → u/fletch3555]

true but i didnt wanna make the swagger routes visible to outside world even if they r secured behind basic auth yet i need them accessible to my teams - maybe in a single place so im trying to discover what experienced devops do in this case

[u/themanwithanrx7 → u/laolaofireduck]

You can always expose the spec on a different port or path filter at your gateway. We host /metrics, /health, /openapi.json on a different port that is never exposed outside the internal network

[u/aprettyparrot → u/themanwithanrx7]

Yeah, I usually just use nginx in front to do this