Skip to content
Docs

OpenAPI Auto-Documentation

What Is OpenAPI Auto-Documentation?

Section titled “What Is OpenAPI Auto-Documentation?”

AgentWatch automatically generates an OpenAPI 3.0 specification from your configured gateway routes, providing always-current API documentation without any manual effort. As you add, modify, or remove gateway routes, the documentation updates automatically within 60 seconds — there is no separate doc-writing step.

This is particularly useful for teams that need to share the AgentWatch gateway API surface with developers building integrations, or for internal compliance documentation showing exactly which endpoints exist and what schemas they enforce.

How It Works

Section titled “How It Works”
  1. Route introspection — AgentWatch scans all active gateway routes and converts each one into an OpenAPI paths entry with method, summary, parameters, and tags.
  2. Schema embedding — If a route has JSON Schema validation configured (section 7.7), those schemas are embedded as requestBody and response definitions in the spec. This means the OpenAPI spec always reflects your validation rules.
  3. Spec caching — The generated spec is cached for 60 seconds. Route changes appear within one minute.
  4. Swagger UI — A hosted, interactive Swagger UI explorer is served alongside the raw JSON spec so developers can browse and test endpoints without any external tooling.

Key Features

Section titled “Key Features”
Feature Description
Auto-Generated Spec Every gateway route becomes an OpenAPI path automatically
Schema Embedding JSON Schema validation rules are reflected as request/response bodies
Swagger UI Built-in interactive explorer at /admin/gateway/docs
60-Second Freshness Spec regenerates on demand; cached for 60s for performance
Standards Compliant Output is valid OpenAPI 3.0 — importable into Postman, Stoplight, Redoc, etc.

Accessing the Documentation

Section titled “Accessing the Documentation”
Resource URL
Raw OpenAPI 3.0 JSON GET /admin/gateway/openapi.json
Interactive Swagger UI GET /admin/gateway/docs

Both endpoints require an admin API key (Authorization: Bearer <admin-key>).

Step-by-Step: Viewing the Gateway API Docs

Section titled “Step-by-Step: Viewing the Gateway API Docs”
  1. Navigate to Settings → API Docs in the sidebar.
  2. The embedded Swagger UI loads showing all your configured gateway routes.
  3. Click any endpoint to expand it. If schema validation is configured, the request/response schemas appear inline.
  4. Use the Try it out button to test an endpoint directly from the browser using your API key.
  5. To import into Postman or another client, download the spec: GET /admin/gateway/openapi.json.

Step-by-Step: Importing into Postman

Section titled “Step-by-Step: Importing into Postman”
  1. Download the spec: curl -H "Authorization: Bearer <key>" https://<gateway>/admin/gateway/openapi.json > agentwatch-api.json
  2. Open Postman → Import → select agentwatch-api.json.
  3. All gateway routes appear as a Postman collection with pre-filled schemas.