Publishing a Specification
Services publish their API specification to SelfDocHub with one HTTP call, usually from a CI pipeline. This page explains the request, the token, branches and what happens to a published document.
Prerequisites#
- A registered service and its upload token. An administrator creates the service in the UI (see Services and Groups) or with
--register-service(see CLI Reference). The raw token is shown exactly once, at creation or rotation. Only a salted hash is stored.
The request#
Send the document itself as the request body, not wrapped in any envelope:
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
Warning: Use
--data-binary, not-d. When reading from a file,-dstrips newlines and silently corrupts a multi-line YAML or GraphQL body into one invalid line.
The service token authenticates the call. It is separate from user sessions and cannot be used to sign in. A token can be rotated by an administrator, and the old one stops working.
Supported formats#
The format is detected from the document itself and accepted as JSON or YAML where applicable:
| Format | Detected by |
|---|---|
| OpenAPI 3 / Swagger 2 | root openapi or swagger field |
| OpenRPC | root openrpc field |
| AsyncAPI | root asyncapi field |
| GraphQL | SDL text, or JSON with a top-level __schema |
The format is locked from the service's first published version. Publishing a different format to the same service later is rejected with 400. See also GraphQL Schemas, OpenRPC and AsyncAPI.
Service name and description#
info.title is required. The service display name is taken from info.title only while the service has no name. A name set at creation or edited by an administrator is never overwritten by a publish. The description, by contrast, follows info.description of every publish.
Branches#
An optional branch query parameter names the documentation branch of the version:
curl -X POST "https://docs.example.com/api/v1/services/billing-api/spec?branch=feature-x" \
-H "Authorization: Bearer $DOCS_UPLOAD_TOKEN" \
--data-binary @openapi.json
It defaults to main. A version becomes the service's current one automatically only when its branch equals the service's main branch setting (itself defaulting to main, editable in the service dialog). Publishing to another branch never changes what everyone else sees. See Versions and Branches.
What happens on publish#
- The token is validated and the document gets a basic shape check.
- An immutable copy of the document is stored as a new version.
- For the main branch, SelfDocHub computes the Change Log against the previous version and makes the new version current.
- The merged documents and navigation are rebuilt.
- A notification is sent if a rule matches.
Re-publishing identical content on the main branch answers 200 OK and creates no new version. On any other branch every publish creates a new version. Old versions beyond history_depth are removed (10 per branch by default).
Limits#
- The document size is limited by
max_spec_bytes(10 MiB by default). If you use Nginx, raiseclient_max_body_sizeaccordingly. - The license may limit the number of operations, methods or fields per service. A publish over the limit is rejected before anything is saved. See License and Tiers.