OpenAPI & Swagger

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/spec/openapi.md
• apps/api/src/infrastructure/http/openapi/registry.ts
• apps/api/src/infrastructure/http/app-router.ts
• apps/api/package.json
• apps/api/test/infrastructure/http/server.integration.test.ts

The Thoth API generates an OpenAPI 3.1.0 document to describe its available HTTP endpoints. It also serves a Swagger UI instance to provide interactive documentation for developers. These features facilitate API discovery and testing during development and testing phases.

Sources: apps/api/spec/openapi.md:7-8, apps/api/src/infrastructure/http/openapi/registry.ts:16, apps/api/src/infrastructure/http/app-router.ts:54-55

Architecture and Components

The OpenAPI system integrates with the Express application via the AppRouter. It utilizes zod-to-openapi to transform Zod schemas into OpenAPI definitions and swagger-ui-express to render the interactive UI.

Key Components

Component	Description
OpenAPIRegistry	Stores definitions for paths, schemas, and parameters.
OpenApiGeneratorV31	Compiles registered definitions into a valid OpenAPI 3.1.0 JSON document.
AppRouter	Mounts the document and UI routes to the Express application.
swagger-ui-express	Middleware that serves the Swagger UI static assets and configuration.

Sources: apps/api/src/infrastructure/http/openapi/registry.ts:6-14, apps/api/src/infrastructure/http/app-router.ts:21-65, apps/api/package.json:30,48

Document Generation Flow

The API generates the specification dynamically when the server starts in non-production environments.

The diagram shows how the system conditionally generates and mounts documentation based on the environment state.
Sources: apps/api/src/infrastructure/http/app-router.ts:53-65, apps/api/spec/openapi.md:16

Configuration and Environment Rules

The availability of OpenAPI documentation is strictly controlled by environment variables. Access is restricted to non-production environments to prevent exposing internal API structures in live deployments.

Endpoint Rules

Route	Rule ID	Behavior
/openapi.json	[RULE-OAS-001]	Serves the raw OpenAPI 3.1.0 JSON document.
/docs	[RULE-OAS-002]	Serves the interactive Swagger UI.
All	[RULE-OAS-003]	Routes are hidden when env.isProd is true.

Sources: apps/api/spec/openapi.md:11-16, apps/api/src/infrastructure/http/app-router.ts:53

Technical Implementation

The implementation relies on a centralized registry where modules contribute their schemas and endpoints.

Registry Setup

The registry.ts file initializes the OpenAPI registry and provides a function to compile the document with metadata such as the title @thoth/api and version 0.0.0.

export function generateOpenApiDocument(): OpenApiDocument {
	const generator = new OpenApiGeneratorV31(registry.definitions);
	return generator.generateDocument({
		openapi: "3.1.0",
		info: {
			title: "@thoth/api",
			version: "0.0.0",
		},
		servers: [{ url: "/" }],
	});
}

Sources: apps/api/src/infrastructure/http/openapi/registry.ts:13-24

Route Mounting

The AppRouter class handles the HTTP exposure. It retrieves the generated specification and uses swaggerUi.setup to configure the web interface.

if (!env.isProd) {
    const spec = generateOpenApiDocument();
    app.get("/openapi.json", (_req, res) => {
        res.json(spec);
    });
    app.use(
        "/docs",
        ...swaggerUi.serve,
        swaggerUi.setup(spec, { customSiteTitle: "@thoth/api" }),
    );
}

Sources: apps/api/src/infrastructure/http/app-router.ts:53-65

Verification and Testing

Integration tests verify that the documentation endpoints respond correctly in the test environment. The tests ensure the specification version is accurate and the UI contains expected markers.

• Document Retrieval: A GET request to /openapi.json must return status 200 and a body where openapi equals "3.1.0".
• UI Accessibility: A GET request to /docs must return status 200 and contain the string "swagger-ui" in the response text.

Sources: apps/api/test/infrastructure/http/server.integration.test.ts:79-90

OpenAPI & Swagger provide a self-documenting interface for the Thoth API, ensuring that endpoint definitions stay in sync with the underlying Zod schemas while maintaining production security.