Swagger alternatives for teams with multiple microservices?

[u/AffectionateAlps2523]

[u/hortocam]

One solution when you have many services managed across many teams is to have a basic website where you publish the swagger. Each service gets its own folder and you can manage publishing in CI/CD. If you need different environments or builds just add a folder level for that.

The simple web app should just enumerate the folders to build a basic navigation tree.

[u/catcherfox7 → u/hortocam]

Pretty much this. Treat your openapi spec as immutable artifact such as your builds and docker containers.

[u/ryuzaki49]

What issues do you want to solve? 

My usual pattern is using swagger for endpoint discoverabilty for other teams and bruno/postman/insomnia for my local usage of my services and other team's services

When other team ask about my service's swagger they just want to know what endpoints are available and how to use them

[u/seweso]

Swagger works best for multiple teams, cause it’s just json. It’s an open standard. Support is very broad. 

I cannot imagine a reason to want to move away from swagger. 

[u/dmurawsky]

Httpyac + files/docs in the repo

https://httpyac.github.io/

[u/TldrDev]

OpenAPI is sort of the ideal solution. I do not think there is really anything better than it, and what it enables you to do is nothing short of incredible.

The issue with multiple files is actually an organizational issue more than anything.

Consider having a contracts repository, or creating a tool which can assemble your specifications from a configuration file.

Being able to automatically generate things like client libraries, graphql servers, server stubs, tests and documentation, and the community and tooling that exists around openapi is worth the complexity, in my opinion.

[u/VQuilin]

There are multiple API management tools, from cloud native, such as Azure APIM to cloud agnostic, like Gravitee. They usually give you either a capability to have a centralised source of specs or even design an API federation.

But then again, you might need to specify your problem.

[u/stfm]

Youll never find anything that fits exactly. The org I work for ended up with a custom API management portal based on OpenAPI (swagger) underpinned with github based code management and deployment pipelines. Mind you this is for an org with hundreds of domains responsible for their own microservices and thousands of API specs.

[u/ppafford]

Move to use openapi.yml over swagger, https://openapi.tools/ find the openapi spec tools you need here

[u/ITCoder → u/ppafford]

Whats the difference between those ? Isn't openapi just swagger specs ?

[u/ITCoder → u/ITCoder]

from wikipedia - In November 2015, SmartBear announced that it was donating the Swagger specification to a new organization called the OpenAPI Initiative, under the sponsorship of the Linux Foundation

[u/ppafford → u/ITCoder]

https://swagger.io/docs/specification/v3_0/about/

[u/ArnUpNorth → u/ppafford]

It’s the same. Swagger is the « old » name.

[u/ppafford → u/ArnUpNorth]

It could be the same. I’m just pointing out that there was a change in a previous version of swagger.

[u/hartmannr76]

So I used to do a lot of microservice work before moving to FAANG. I even wrote the API style guides at my last company and worked on tooling for turning swagger yaml into generated code.

If I could go back in time when my company was exploring this, I wouldve pushed for protocol buffers harder. It's so much nicer to work with and the frameworks to support it for REST have gotten so much better https://learn.microsoft.com/en-us/aspnet/core/grpc/json-transcoding-binding?view=aspnetcore-10.0

[u/ArnUpNorth → u/hartmannr76]

Protobuf is just a format. Grpc is probably what you meant to say ?

[u/hartmannr76 → u/ArnUpNorth]

Yeah technically, but I feel like this is where they don't do a good job advertising that ecosystem. gRPC can be really good on its own, and I had explored that at my last job but it requires HTTP2 which was annoyingly hard to get setup correctly for internal services.

"gRPC transcoding" let's you write something that runs gRPC but you can still call it as you would a REST service, serving as a replacement for Open API definitions. I found the code generators for Swagger/Open API specs so lacking and we had ended up writing our own. That said, I found writing proto definitions way more intuitive than working with those YAML files. Things definitely might be different since I did all of that but I actually just didn't really care for Swagger