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#
- Install SelfDocHub with Docker.
- Register each service and copy its upload token.
- 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.