Endpoint Pages

An endpoint page shows everything about one operation: description, parameters, responses, examples and a Try-It panel. This page explains its parts.

Addresses#

Pages have readable, shareable addresses:

Page Address
Service /docs/{service}
Endpoint /docs/{service}/{method}/{path}
Tag /docs/{service}/tag/{tag}
OpenRPC method /docs/{service}/rpc/{method-name}
AsyncAPI operation /docs/{service}/async/{id}
Text page /docs/{service}/pages/{id}

In an endpoint address, {param} path templates are written as :param, for example /docs/doc-hub/post/api/v1/merged/snapshots/:id. Every address carries branch and version query parameters naming what it shows. See Versions and Branches.

Tabs#

  • Parameters lists parameters followed by the request body. A request body is shown as a collapsed schema tree for each media type. An operation with only a body shows the body schema.
  • Responses lists responses per status code as schema trees.
  • Example Parameters and Example Responses appear only when the specification documents at least one example. Each value is shown as Compact JSON, Formatted JSON or an interactive Tree (the default). The JSON tabs have a copy button.
  • Errors appears for OpenRPC methods that list errors.

Each field row has buttons to copy a link to it and to open its description. A dot marks a description that comes from an overlay.

Adding query parameters to Try-It#

On a GET endpoint, hover over a query parameter or a nested property to see Add to the Try-It query. It appends name=value to the Try-It Query field and opens the Try-It section if collapsed. Arrays add [] (ids[]=7), object properties use brackets (filter[status]=done). The value is random and fits the type, enum and format (date, UUID, e-mail, URL, IPv4 and so on).

Generating a request body#

When an operation has an application/json request body and its method is POST, PUT or PATCH, the Try-It Body field has a Generate button. It fills one fake value per field, following $ref and allOf. Only application/json bodies are supported, and a failed generation leaves your text untouched.

Description, title and original#

Editors can replace the title and description with an overlay. When an overlay is active, a Show Original / Show Overlay toggle lets any viewer compare it with the pre-overlay text. The toggle is visual only and never saved.

Labels#

A line above the page shows the tags of the specification (not removable) and manual labels. Administrators and editors add and remove labels. See Text Pages.

Change History#

The Change History block lists what changed for this endpoint in each version, with a Breaking mark. See Change Log.

Tag pages#

A tag page lists its endpoints and the tag description. Administrators and editors can edit or delete the tag's label and description there. A tag page always lists every endpoint of the tag, including those moved out of it in the structure.

Next steps#

Screenshots

Last updated: