Copy page

Configuration

API reference

The portal's API Reference page, at /api, is made from your gateway's OpenAPI file. There is nothing to set up: when the project has a gateway with specs, the page is there.

apitogo.config.json
{
  "gateway": {
    "origin": { "mode": "managed", "source": "server", "runtime": "nodejs" },
    "specs": ["apitogo/apis/openapi.yaml"]
  }
}

The page uses the first file in specs. JSON and YAML both work.

What the page shows

The page shows your API as people call it, through the gateway, not as it runs behind it:

• Servers point at the gateway's address. Your origin's address never shows.
• Security says what the gateway checks: the API key header (X-API-Key unless gateway.policies.access.apiKeyHeader names another), and a bearer token when gateway.auth is set.
• Operations in gateway.policies.operations.public show no security, since they need no key.
• Operations in gateway.policies.operations.deny are left out.

Before the first deploy the gateway has no address yet, so apitogo run leaves the page out and says so. It appears once the gateway is deployed.

Try it

Each operation has a Try it panel that sends a real request to the gateway. Under Authentication it offers:

• Your API key: a key the visitor created on the API keys page, in this browser.
• Signed-in user: the visitor's own sign-in token. It is offered only when the gateway checks tokens (gateway.auth), since a gateway that checks keys would answer it with 401.

Turn the panel off for one operation with x-apitogo-playground-enabled: false (below).

Who may read the OpenAPI file

The platform also publishes the file for other docs tools. By default anyone may read it. To limit it to signed-in people:

Code
"gateway": { "export": { "access": "authenticated" } }

OpenAPI extensions

Fields starting with x- in your OpenAPI file change how the page looks.

Operations

• x-apitogo-playground-enabled: show Try it for this operation (default true). x-explorer-enabled is the same.

Code
paths:
  /users:
    get:
      summary: Get users
      x-apitogo-playground-enabled: false

Tags

• x-apitogo-collapsed: the tag's section starts collapsed (default true).
• x-apitogo-collapsible: the tag's section can be collapsed (default true).

Code
tags:
  - name: Users
    x-apitogo-collapsed: false

Tag groups

Group tags in the sidebar with x-tagGroups at the root of the file:

Code
x-tagGroups:
  - name: Shipment
    tags: [Packages, Parcels, Letters]

Page title and description

The page's title and description come from the file's info: info.title, and info.summary (or info.description when there is no summary).