Swagger UI on every service vs one portal

Swagger UI is the default answer to "how do we document our API": add it to the service, expose /docs, done. It works well for one service. With twenty, the cracks show, and that is the moment teams look for a portal.

What changes with many services#

Swagger UI in each service One SelfDocHub portal
Finding an endpoint Know which service has it, then open its address One search across all services and text pages
Documentation of a service that is down Unavailable with the service Stays available: it is stored in the portal
History The spec of the version that is deployed Every published version, with a change log and breaking changes flagged
Access control Whatever each service does Teams and roles decide who sees which service; SSO
Try-It Against the deployed service, one at a time Named environments, saved and shareable requests
Maintenance A copy of the library in every service One server to run
Other formats OpenAPI/Swagger Also GraphQL, OpenRPC and AsyncAPI

What stays the same#

Your services keep generating their OpenAPI file the way they do now. SelfDocHub reads that file, so there is nothing to rewrite and no new annotation format to learn.

How to move#

  1. Install SelfDocHub with Docker.
  2. Register each service and copy its upload token.
  3. Add one step to CI that sends the OpenAPI file after a successful build.
curl -X POST https://docs.example.com/api/v1/services/billing-api/spec \
  -H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @openapi.json

When plain Swagger UI is enough#

One or two services, a public API with its own documentation site, or a local development tool that nobody needs to search. Then the extra moving part is not worth it.

Frequently asked questions

Do I have to stop using Swagger UI in my services?

No. Keep it for local development if you like. SelfDocHub reads the same OpenAPI file, so there is nothing to rewrite.

Can SelfDocHub import my existing specs?

Yes. Publish each service's OpenAPI file with one HTTP call, or import a file by hand in the interface.

Run it on your own infrastructure

The Free plan includes a license for one installation. Start with Docker in a few minutes, no credit card needed.