API Docs Configuration

API Docs Configuration

Every ɳSelf deployment generates a live interactive API reference automatically. No manual spec writing required.

Two endpoints are served by nginx after nself build:

Endpoint	Content
/api-docs	Raw OpenAPI 3.1 JSON spec
/docs	Scalar interactive docs page (offline-capable)

The spec is built from:

1. Hasura GraphQL schema (auth endpoints, REST-over-GraphQL)
2. REST endpoints from nself custom services
3. REST routes contributed by installed plugins via plugin.json rest_routes

Configuration

Add an api_docs section to your project’s .env file (or export the env vars):

.env.dev

API_DOCS_ENABLED=true             # default: true. set false to remove the nginx blocks
API_DOCS_PATH=/docs               # serve path for the Scalar page
API_DOCS_TITLE="My App API"       # defaults to "<project_name> API"
API_DOCS_THEME=default            # default | moon | purple | solarized
API_DOCS_AUTH_ENV_VAR=NSELF_ANON_KEY  # env var whose value pre-fills the bearer token
API_DOCS_GRAPHQL_ENABLED=true     # include GraphQL section (default: true)
API_DOCS_GRAPHQL_ENDPOINT=/v1/graphql

Disabling

Set API_DOCS_ENABLED=false and re-run nself build. The nginx location blocks for /api-docs and /docs are removed entirely. No stub page is served.

Themes

Scalar ships four built-in themes. Set via API_DOCS_THEME:

Value	Description
default	Light/dark system theme (default)
moon	Dark, low-contrast
purple	Dark, purple accent
solarized	Solarized light

Offline operation

Scalar is vendored inside the CLI binary and served from disk. The /docs page makes no external network requests. It works on air-gapped hosts and local dev with no internet access.

GraphQL schema explorer

When API_DOCS_GRAPHQL_ENABLED=true, the spec includes:

• POST /v1/graphql: executable try-out for queries and mutations
• GET /v1/graphql/subscriptions: documented as WebSocket (x-nself-websocket: true), not executable in the REST try-out panel

Auth pre-fill

Set API_DOCS_AUTH_ENV_VAR to the name of an env var that holds your anon JWT. Scalar pre-fills the bearer token input on page load, so try-out requests work without manual copy-paste.

API_DOCS_AUTH_ENV_VAR=NSELF_ANON_KEY

The token value is read at build time from the resolved env cascade and embedded in scalar.html. Rotate the token and re-run nself build to update.

Hiding endpoints

To exclude specific paths from the generated spec, set API_DOCS_HIDE_ENDPOINTS as a comma-separated list of path prefixes:

# Hides all /internal/* and /admin/* paths
API_DOCS_HIDE_ENDPOINTS=/internal,/admin

Plugin-contributed endpoints

Plugins can register REST routes by adding a rest_routes key to their plugin.json:

{
  "name": "ai",
  "rest_routes": [
    {
      "method": "POST",
      "path": "/ai/v1/complete",
      "summary": "Text completion"
    },
    {
      "method": "POST",
      "path": "/ai/v1/embed",
      "summary": "Embedding generation"
    }
  ]
}

These routes appear as a tagged group (tag = plugin name) in the generated spec.

Generated files

nself build writes three files:

File	Purpose
.nself/dist/openapi.json	OpenAPI 3.1 spec
.nself/dist/scalar.html	Self-contained Scalar page
nginx/conf.d/api-docs.conf	nginx location blocks (hand-managed dir, safe to keep across builds)

The .nself/dist/ files are regenerated on every build. The nginx conf in conf.d/ is also regenerated but lives in the hand-managed directory, do not edit it manually.

Related

• Service Inventory
• Environment Variables
• Plugin development