Visualizing Multiple APIs with Swagger

TLDR — Want to visualize and interact with multiple OpenAPI Spec (OAS) APIs in one place? Check out vite-swagger-ui, a Swagger UI setup powered by Vite with built-in support for multiple APIs.

The problem

It's hard to beat Swagger UI when looking for a free way to document OpenAPI Spec (OAS) APIs. It has a decent UI, is interactive, and is fairly simple. In many cases, I prefer it over something more complex like Postman.

But I recently was working on a distributed system with several APIs — deployed from a single monorepo — and wanted a way to visualize all of the APIs in one place.

I knew this was possible with Swagger UI, but I couldn't find good documentation on how to make it work. I also wondered if there was a better solution on the market at this point. I hadn't taken a look in a while.

So I decided to research the OAS documentation generation landscape a bit and come up with a solution.

Evaluating the landscape

The OAS tooling landscape is vast and continues to grow, so I wasn't exactly sure where to start.

Fortunately, I came across a helpful resource called OpenAPI.Tools that lists out many of the most popular tools in the OAS space.

Funnily, Swagger UI is not on that list, but I did find the list helpful for seeing the landscape at a high level.

One particularly beautiful documentation generator, Bump.sh stood out and captured the simplicity I was looking for while also supporting multiple APIs in a nice way. Alas, I specifically wanted a solution that was free and open source, so Bump.sh and a lot of the other tools on the OpenAPI.Tools list were out of the question.

In the end, there were only a few options worth considering alongside Swagger UI: Redoc and a newcomer called Scalar.

Scalar is the best OAS documentation generator I have come across by far. It is well-organized, aesthetically pleasing, and performant. Unfortunately, it, and the more well-known but less enticing Redoc, doesn't handle displaying multiple APIs out of the box.

Now, I know I can use Redoc, Scalar, or Swagger UI as a component in React — or plain JS for that matter — and build a solution for toggling between multiple APIs myself. And that would actually be quite simple. But I wanted to use a generator that had support for multiple APIs baked in.

So I decided to stick with Swagger UI and figure out how to configure it to my needs (though I am tempted to build around Scalar in the future).

Building a solution

Through trial and error, I came up with a working solution powered by Vite. Doing so, though, ended up taking a large chunk of time. Even though it is supported, there simply isn't good documentation or a good example of how to document multiple APIs with Swagger UI.

So, I decided to change that.

In hopes of helping someone looking for a similar solution, I built vite-swagger-ui. It contains a pre-configured Vite and Swagger UI setup that supports multiple APIs and is easy to use. All you need to do is bring your spec files and run.

Check it out here.

If you find it helpful, I'd love to hear from you!

@lukefernandezio