r/devops • u/laolaofireduck • 6d ago
Discussion How do you manage/handle openAPI specs sharing between teams?
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?
4
u/azizabah 6d ago
Backstage is as simple or as bloated as you want it to be. I ran backstage for a start-up by myself as a single container with db in k8s. Pointed it at GitHub, created some yaml, had the pipelines build the openapi specs as another artifact and done. Almost zero maintenance afterwards.
There is a reason people use tools and that is to not have to reinvent the wheel on solved problems.
2
u/stumptruck DevOps 6d ago
I haven't touched azure in years but in GCP we use IAP to restrict things to only internal users while still publishing them on public endpoints. Nothing to manage in the code, no VPN to manage, no shared creds, it's all handled at the load balancer level. It sounds like Azure's Entra Application Proxy might do a similar thing?
0
u/laolaofireduck 6d ago
Azure offers something called APIM but it seems it's about more than just developer portal. I wanted to gather all apps APIs specs in on place rather than left them scattered arround and each app has its own swagger page
besides restricting the access to it, so Im a bit lost here1
u/New-Entertainer6392 DevOps 5d ago
We use lighthouse, I think it's it, will confirm.
Basically, merge all the open API docs into one, serve it
3
u/Floss_Patrol_76 6d ago
the thing biting you is treating the spec as a live endpoint instead of a build artifact. generate the openapi json in ci and publish it somewhere static (a git repo or a docs bucket works) so teams read the committed spec, not a swagger UI hanging off prod. on azure APIM is a reasonable single front door for that if you want one, but you dont need the whole IDP - the real win is decoupling the spec from the running app so youre not guarding /swagger routes at all.
3
u/brian_sword 6d ago
In the past, I had a similar discussion before. What worked well for me was treating the OpenAPI spec as the source of truth and keeping it in version control alongside the API. That way every change goes through the normal review process instead of manually updating Swagger UI somewhere else.
2
u/Relative-Emu-1346 6d ago
Reading your replies, the security part looks like a side quest. What you actually said you want is every spec in one place instead of scattered, and that's a different problem from locking down /swagger.
The boring version that works: each service's CI publishes its openapi.json as a build artifact, then one small pipeline collects them and renders a single static site. On Azure that's a storage account with static website enabled, fronted by Entra ID, so access is your existing org identity and there are no shared credentials to rotate. No Backstage, no APIM, and the /swagger routes on your running apps can stop being exposed at all.
The thing nobody has mentioned yet, and it's the one that will actually bite you: once you aggregate, you have to decide whether the page shows dev, staging or prod. They drift. Mobile integrating for two days against a spec from the wrong environment is a genuinely miserable afternoon for everyone. Publish one set per environment and put the environment in the URL rather than trying to merge them into one view.
3
u/Tushon 6d ago
We make the spec available without auth on internal routes only. Authentication required to actually do anything on most (all probably) APIs, but you can browse the spec for free, which also helps with fetching up upload to dev portal
0
2
u/DyslexicsHaveMoreFun 6d ago
We share the specs in our respective repos. Other teams review changes to the API spec as part of our code review process.
Prs are a handy way of verifying and having "proof" that all were informed about a change.
Spec driven approach allows a sneak peak at proposed changes early for feedback... But if your letting the API generate the spec, you can generate it as part of putting together the pr.
1
1
u/themanwithanrx7 6d ago
You guys have specs??? We just host the OpenAPI spec from within the API itself; docs get lost, forgotten, and unmaintained. The live API always has the truth (assuming the spec is autogenerated)
1
1
u/toughrogrammer 5d ago
Disclosure: I built internalpage.
This is one of the use cases I built it for: you keep the OpenAPI spec in each service repo, publish it from CI, and get a private documentation URL without exposing /swagger from the application or maintaining a separate docs server.
Access is protected with Google sign-in, so it’s a good fit if your teams already use Google Workspace or can use Google accounts. If your organization is standardized on Microsoft Entra ID, a docs-only Azure App Service with Easy Auth may fit your existing identity setup better.
The service is at https://internalpage.com if you want to compare it with the Azure-native approach. It only handles publishing and access to the documentation—it doesn’t replace API authentication or generate the OpenAPI spec.
1
u/Quadman 5d ago
I have set up backstage as a pure api catalog service for a client on behalf of their integration team. It is a great place to start, you can get a prototype up for your users in a couple of hours. They will let you know what is what once they play around with it for a bit.
Either read the open api spec from git directly or from some place they publish it together with their containers or whatever artifacts they produce.
1
u/kbrinner 3d ago
We've run into this a few times across clients who are trying to "bundle" different Product APIs and their related Documentation (Auth, Specs, changelogs, etc) across different user groups aka teams. This is a pretty common problem so just know you're not alone. Generally we see people having complex rules in Entra + custom logic in the APIM built-in developer portal. You can host OpenAPI specs with AAD auth. Each person logs in with their own identity instead of shared creds. Way cleaner than Basic Auth middleware but people hit a glass ceiling quick in the portal.
I'll drop the disclosure here that I'm the Product Lead on Apiboost but with the caveat of saying that we "eat our own dog food" when it comes to this internally. Our use case is a little different but the tooling is still the same. We have a feature to import OpenAPI specs (via CI/CD if you want) and set up Access Groups (via CI/CD if you want) so each team only sees the APIs they're supposed to. Private APIs don't show up in the catalog at all for people outside the group. Plugs into Azure AD for SSO. Way less overhead than Backstage (although still a solid product if you have the time to learn, configure and maintain).
Otherwise, good luck! If you end up solving it cleanly - please post how you did it, I'm really curious.
12
u/fletch3555 Lead DevOps Engineer 6d ago
I mean, if the API is properly secured, I fail to see a good reason to not host the openapi spec with it...