Skip to main content

Swagger UI

Agentium can generate an OpenAPI 3.0 spec and serve Swagger UI for your agent, team, and workflow endpoints. Enable it via swagger.enabled in createAgentRouter() options.

Quick Enable

This serves:
  • Swagger UI at /docs
  • OpenAPI spec at /docs/spec.json

SwaggerOptions

boolean
default:"false"
Set to true to enable Swagger UI and spec generation.
string
default:"Agentium API"
API title shown in Swagger UI.
string
API description. Default: auto-generated from agents/teams/workflows.
string
default:"1.0.0"
API version string.
string
Route prefix used in path generation (e.g., /api). Paths in the spec will include this prefix.
Array<{url, description?}>
Server URLs for the OpenAPI spec. Useful for staging/production URLs.
string
default:"/docs"
Path to serve Swagger UI.
string
default:"/docs/spec.json"
Path to serve the raw OpenAPI JSON spec.

Full Example


Dependencies

Swagger UI requires swagger-ui-express:
If swagger-ui-express is not installed, Swagger UI is disabled and a warning is logged.

Generated Spec

The OpenAPI spec includes:
  • Paths for each agent, team, and workflow
  • Schemas for RunRequest, RunOutput, StreamChunk, MultipartRunRequest
  • Per-agent structured output schemas — agents with structuredOutput get a dedicated response schema (e.g., RunOutput_analyst) that includes the full typed structured field
  • Token usage with providerMetrics — the usage schema includes a providerMetrics object field containing raw provider API data
  • Security schemes for provider-specific API keys (x-openai-api-key, x-google-api-key, x-anthropic-api-key, x-api-key)

Structured Output in Swagger

If an agent has a structuredOutput Zod schema, Agentium automatically converts it to JSON Schema and includes it in the OpenAPI spec. The structured field in the response is fully typed — API consumers see the exact shape of the data.
The spec for POST /agents/analyst/run will use the RunOutput_analyst schema with:
Agents without structuredOutput use the generic RunOutput schema where structured is untyped.

Fetching the Spec

Use the spec URL with external tools (Postman, Insomnia, code generators) or embed it in other documentation.