API Documentation using OpenAPI Specification with multiple spec at a central place

Question

We have a lot of micro services exposing their APIs and we have an API first approach. Each service has its own OpenApi3.0 spec file mostly in yaml or json format in their own git repo.

However, like other companies in the wild, my team and other internal teams are facing trouble with discovering the API and the documentation around it. I would like to build a central place which can render all the API Specs and make things easily discoverable. May be at par with say Stripe or twitter documentation standards.

So far, I have found few ways to achieve it :

1. Use React framework to render Redoc components for each spec separately. Makes it scalable but searching across services could be difficult.

2. Merge all the api specs using some pre-existing tools and convert it to MarkDown to show in Slate or use Docusauras with React Redoc stuff. Merge using https://www.npmjs.com/package/openapi-merge-cli and widdershins with slate. In a company with several apis , scaling would be an interesting challenge i assume with this approach.

I do not want to rely on SwaggerHub as it ties me to something specific. Again, i am looking for open source stuff with license that permits commercial usage.

Would love to get some suggestions / experiences or if there exists something similar and i can avoid reinventing the wheel.

Answer 1

It seems that there are not a lot of open-source solutions to this yet. In the repo, Redoc has a sample of how you might combine multiple services' spec files here.

There is also another example here with a slightly better API. It's also packaged with Docker which should make getting up and running easier.