# 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](/documentation/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.

---
Source: https://selfdochub.com/features/merge-openapi-specs
