Octopus config fragments

When the config: section is present, the generator walks each spec's paths, skips skip_paths and any method outside GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS, and emits gateway routes plus an upstream definition per service.

With split: true (the default) it writes two files per service, named from the service name:

generated/
  example.routes.yaml      # { routes: [...] }
  example.upstream.yaml    # { upstreams: [...] }
  portal.routes.yaml
  portal.upstream.yaml

With split: false it writes a single generated-config.yaml (or .json) containing both merged routes and upstreams arrays. The extension follows format (yaml or json).

A generated route carries the prefixed path, the HTTP method, the upstream name, and — when a prefix is set — a strip_prefix. Auth fields from the service are copied in; if the spec marks an operation as having no security while the service declares auth, that route gets skip_auth: true.

# example.routes.yaml (excerpt)
routes:
  - path: /example/api/v1/users
    methods:
      - GET
    upstream: example
    strip_prefix: /example
    auth_provider: internal-jwt
    require_roles:
      - user

# example.upstream.yaml
upstreams:
  - name: example
    lb_policy: round_robin
    instances:
      - id: example-1
        host: localhost
        port: 7900

These map directly onto the gateway's routes and upstreams config. The split fragments include the per-route skip_prefix/require_scopes/skip_auth fields; the merged file emits a slightly leaner route shape (path, methods, upstream, prefix, provider, roles).

The Octopus Schema

When the schema: section is present, the generator writes a single intermediate JSON document (default octopus-schema.json, under output_dir unless the path is absolute or starts with .). This is the contract the TypeScript client is generated from — and it is also built in-memory when generating the client, so the client works even if you omit the standalone schema: output.

It contains:

• A top-level $schema, version, and generated_at (Unix seconds).

• A services map: per service, the base_path, upstream (host/port), optional auth (strategy: bearer, provider, roles, scopes), an operations map keyed by scope, and a channels map for WS/SSE.

• A types map: every DTO extracted from the spec's components.schemas, cleaned for output (x-* extensions, xml, and example are stripped; $refs are rewritten to #/types/<Name>).

Each operation records its method, path, summary, tags, params (split into path/query/header), and request_body/response type references. Array responses (e.g. an OpenAPI array of $ref: User) are recorded as #/types/User[].

Scopes

Every operation is assigned a dot-separated scope like example.users.list. The scope determines where the operation lands in the client's namespace chain. Scopes resolve in priority order:

1. Manual mapping from the service's scopes: block (exact path + METHOD).

2. operationId from the spec — listUsers → example.users.list, users_list → example.users.list.

3. Path + method heuristics — the resource segments of the path plus a verb derived from the method.

The path heuristic skips api and version segments (v1, v2, …) and path parameters, then chooses a verb based on whether the path ends in a parameter:

So GET /api/v1/users → example.users.list, GET /api/v1/users/{id} → example.users.get, and GET /api/v1/users/{userId}/posts → example.users.posts.list. Use the scopes: block to override any of these explicitly.

TypeScript client SDK

When client.enabled: true, the generator writes a TypeScript package into client.output_dir. The client is namespace-chained: the scope path becomes the call path. example.users.list becomes client.example.users.list().

import { createClient } from '@myapp/api-client';

const client = createClient({
  baseURL: 'https://gateway.example.com',
  auth: { token: process.env.API_TOKEN },
});

// Namespace chain mirrors the scope: example.users.list
const users = await client.example.users.list();

// Path/query/body params are passed as a typed options object
const user = await client.example.users.get({ path: { id: '123' } });
const created = await client.example.users.create({ body: { name: 'Ada' } });

The emitted package layout is:

generated/client/
  package.json                  # name, exports, TanStack peerDependency
  index.ts                      # createClient() + per-service factories
  types.ts                      # generated DTO types
  core/
    types.ts                    # ClientConfig, AuthConfig, RequestConfig, ApiError
    fetcher.ts                  # the request() implementation (auth, timeout, interceptors)
    ws.ts                       # WebSocket runtime (only if a service has WS channels)
    sse.ts                      # SSE runtime (only if a service has SSE channels)
  services/
    example/                     # one folder per service: index.ts + per-namespace files
    portal/
  tanstack/                     # only if tanstack_query.enabled
    example.hooks.ts
    portal.hooks.ts
    index.ts
  per-service/                  # only if per_service_packages: true
    example/{package.json,index.ts}
    portal/{package.json,index.ts}

ClientConfig (from core/types.ts) takes baseURL, default auth, headers, cookies, credentials, a timeout, an optional custom fetch, and onRequest/onResponse interceptor arrays. Each call accepts the same per-request overrides plus signal, responseType, and timeout. Auth defaults (header name, prefix, strategy) come from client.auth.

The generated package.json is marked private with version: "0.0.0", main/types pointing at index.ts, an exports map (., ./types, and ./tanstack when hooks are enabled), and a @tanstack/react-query peer dependency derived from tanstack_query.version. It is meant to be consumed in-tree by a TypeScript toolchain, not published as-is.

TanStack Query hooks

With client.tanstack_query.enabled, the generator emits a hook per operation under tanstack/, one file per service plus a barrel index.ts. Read operations (GET) become useQuery hooks; write operations (POST/PUT/DELETE/PATCH) become …Mutation hooks built on useMutation. Hook names are derived from the service name and the relative scope (e.g. example.users.list → useExampleUsersList), and the full scope is used as the query key.

import { useExampleUsersList } from '@myapp/api-client/tanstack';

function UserList(config) {
  const { data, isLoading } = useExampleUsersList(config);
  // ...
}

version: 5 and version: 4 both import from @tanstack/react-query; any lower value imports from the legacy react-query package.

Per-service packages

With client.per_service_packages: true, the generator also emits a standalone re-export package per service under per-service/<service>/. Each is a small package.json (named <package_name-without-/api-client>-<service>, private, 0.0.0) plus an index.ts that re-exports that service's factory (e.g. createExampleService as createExampleClient) and the shared types from the main package. This lets a frontend depend on just the slice of the API it uses.

WebSocket & SSE clients (AsyncAPI)

For asyncapi services, channels become typed real-time endpoints. WebSocket channels are mapped to /ws<channel> and SSE channels to /events<channel>; protocol is detected from the x-protocol extension, ws/http bindings, or SSE-flavored tags. The schema records each channel's send/receive message types, and the client emits a typed ws.ts/sse.ts runtime plus channel methods on the service namespace. These runtimes are only written when a service actually defines channels of that kind, gated additionally by client.websocket.enabled / client.sse.enabled.