Scattered API documents gathered into one orderly portal

One API documentation portal for dozens of microservices

When a company has three services, documentation is a non-problem: each service exposes a Swagger page and everybody knows the three addresses. At thirty services the same setup quietly turns into a tax. This post describes what breaks and what a single portal changes.

Where per-service documentation breaks#

Nobody knows where to look. The first question in every integration is "which service has this endpoint, and where is it documented?". The answer lives in someone's head or in a wiki page that is out of date.

There is no search across services. Each Swagger page searches only itself. Finding "the endpoint that creates an invoice" means opening several services.

Documentation disappears with the service. If a service is down, redeploying or not running in the environment you are looking at, so is its documentation.

There is no history. The page shows the specification of whatever version is deployed. Nobody can answer "what changed in the last release?" without diffing two files.

Everything is different. One service uses Swagger UI, another Redoc, a third has a Markdown file, the GraphQL service has nothing at all.

What a portal gives you#

A portal inverts the flow. Instead of every service serving its own documentation, every service pushes its specification to one place, and readers go to one place. That gives you:

  1. One address and one search for everything, including the hand-written guides that explain how services fit together.
  2. Stored versions, so documentation is available independent of the running service and every version can be compared with the previous one.
  3. Consistent navigation: services grouped by domain, tags and folders arranged for readers rather than in the order the code generator produced them.
  4. Access control that follows teams, so a contractor sees one service rather than the whole company.

What must not change#

A portal is useful only if publishing to it is nearly free. If teams have to learn a new annotation format, write configuration files or open tickets, documentation will lag again. The workable shape is the one every service already supports: generate the OpenAPI file you generate today and post it from CI, with one command, using a per-service token.

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

That is how SelfDocHub works: a service token authenticates the call, the document is stored as an immutable version, merged with the rest of the portal and published. Posting identical content again changes nothing, so it is safe on every build.

Practical advice for the rollout#

  • Start with the services people ask about most, not all thirty. Each one added to the portal removes questions.
  • Name services after what they do, and group them by domain (Payments, Identity, Internal tools) so the portal reads like a map of the company.
  • Write one text page per domain: how the services fit together, who owns them and where to ask. Generated reference cannot say that.
  • Publish from the main branch only at first. Add per-branch previews once the habit exists.
  • Turn on notifications for breaking changes and send them to the channel of the consuming teams.

Self-hosted, or not#

Internal APIs describe internal systems, so many companies want the portal inside their network. SelfDocHub is a single binary with its web interface embedded and no separate database server, so running it is closer to running a static site than to running a platform. Read the Quick Start to see it with your own specifications in a few minutes, or compare it with other options on the comparison pages.

Frequently asked questions

Should every team keep its own documentation site?

It works for a handful of services. Past that, developers lose time asking where an API is documented, and nobody can search across services. A single portal fed automatically from CI removes both problems.

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.