Several separate API documents merging into one

Merge multiple OpenAPI specs into one portal

The usual advice for documenting a system of microservices is to "merge the OpenAPI files". Doing it by hand means a script that rewrites paths, renames conflicting schemas and fixes $ref pointers, and someone has to keep it running. SelfDocHub does the merge for you, on every publish, and keeps each service independent.

What "merge" means here#

Every service publishes its own specification and keeps its own history. SelfDocHub builds a merged document for each service and presents all services in one interface, with one search and one menu. For OpenAPI the rules are simple and predictable. For a service with the slug billing-api:

Area Result
Paths /invoices is shown as /billing-api/invoices
Tags invoice becomes billing_api_invoice
Components Invoice becomes billing_api_Invoice
$ref Local references are rewritten to the new names
operationId Prefixed with the slug; duplicates get a numeric suffix

Because each service has its own merged document, reading one endpoint does not get slower when you add services, and the same merged data is what the interface, the exports and the MCP server read. The full rules are in Merge Rules.

Different formats side by side#

You do not have to choose one format for the whole company. OpenAPI and Swagger, GraphQL, OpenRPC and AsyncAPI services live in the same portal. Each service uses exactly one format, detected from its first published version, and the format is locked afterwards so a pipeline cannot publish the wrong kind of document by mistake.

Failures stay local#

A service whose specification is invalid or unreadable is skipped and reported in the diagnostics, while the rest of the portal keeps working. Limits from your license (operations per service, services in total) reject an oversized publish before anything is saved, so the portal never ends up half updated.

Organize what you merged#

Merging is only half of a good portal. You can group services into named blocks with icons, arrange each service into folders, tag groups, endpoints and text pages, and give each team access only to the services it needs. Overlays let you improve descriptions in Markdown without editing the source specification, and they survive new versions.

Try it with your own specs#

Install SelfDocHub with Docker, register two or three of your services and publish their specifications. The Free plan allows three services, which is enough to see how your real APIs look side by side.

Frequently asked questions

Do I have to combine my services into one OpenAPI file myself?

No. Each service publishes its own specification. SelfDocHub builds a merged document per service and shows all of them together in one interface, so you never maintain a hand-merged file.

What happens if two services use the same schema name?

Names never collide: components, tags and operation ids are prefixed with the service slug, for example Invoice becomes billing_api_Invoice, and local $ref pointers are rewritten to match.

What if one specification is broken?

A service whose specification is invalid or unreadable is skipped and reported in the diagnostics. The other services keep working.

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.