What’s a clean way to share and secure OpenAPI specs across teams?

The cleanest approach is usually to stop treating Swagger as a live endpoint. Keep the OpenAPI file in the service repository, or generate it during CI, and require spec changes to go through the normal pull-request review process. CI can then publish the approved `openapi.json` as an artifact or to a private static documentation site.

That separates the contract from the running application, so you can remove the publicly exposed `/swagger` route entirely. It also gives other teams an early look at proposed API changes before they reach an environment.

Azure API Management can provide a central place for API definitions and a developer portal, but it may be more platform than you need if the goal is only documentation. An internal docs site protected at the load balancer or application gateway layer can solve the access problem without adding authentication code to every API.

The important distinction is that the documentation site should use Entra-based SSO or another existing identity provider, while the APIs still enforce their own normal authentication and authorization. Access to the spec should not be mistaken for access to the API.

Backstage does not have to be a huge platform. It can run as a relatively small internal catalog that reads specs from Git or from CI-produced artifacts. However, if all you need is searchable OpenAPI documentation, version control plus a private static site is probably the lower-maintenance choice. Start with the simple pipeline and add a catalog later if teams need ownership, dependencies, changelogs, or service metadata.

A private internal route can also work if your network already has clear boundaries—for example, only allowing traffic from corporate IP ranges or an internal network. The OpenAPI document can remain available without its own application-level login while the actual API requires authentication.

That said, an identity-aware gateway is generally easier to manage than IP allowlists when teams work remotely or from different networks. Either way, avoid one shared credential across all environments and services.

For a central catalog, have each service publish its spec from CI and use a small aggregation job to build one static documentation site. On Azure, a Storage Account static website or a lightweight App Service can work, with Microsoft Entra ID or Easy Auth in front of it. Everyone uses their own organization account, so there are no shared Basic Auth credentials to rotate.

Publish separate catalogs or paths for Dev, Staging, and Prod rather than silently merging them. Specs tend to drift between environments, and integrating against the wrong version can cause a lot of confusion.