OpenAPI¶

Overview¶

Katal can generate an OpenAPI 3.1 document from registered routes and validation schemas.

Quick Start¶

import { Application, Controller } from "katal";

const app = new Application({ port: 3000 });
const router = app.getRouter();

class CreateUserController extends Controller {
    async handle(context) {
        return this.success({ id: 1, ...context.body });
    }
}

router.post("/users", CreateUserController, {
    validation: {
        email: { required: true, type: "email" },
        name: { required: true, type: "string", minLength: 2 },
    },
    docs: {
        summary: "Create user",
        tags: ["Users"],
        operationId: "createUser",
        responseDescription: "User created",
    },
});

// Expose generated OpenAPI at /openapi.json
app.exposeOpenApi();

await app.listen();

API¶

`app.getOpenApiDocument(options?)`¶

Returns the generated OpenAPI JSON object.

`app.exposeOpenApi(path?)`¶

Registers a route that serves OpenAPI JSON. - Default path: /openapi.json - Custom path example: app.exposeOpenApi("/docs/openapi.json")

Route Metadata¶

Use docs in route options:

router.get("/users/:id", GetUserController, {
    docs: {
        summary: "Get user by id",
        description: "Returns a single user",
        tags: ["Users"],
        operationId: "getUserById",
        responseDescription: "User response",
    },
});

Supported docs fields: - summary - description - tags - operationId - responseDescription

Validation Integration¶

If a route has validation, Katal automatically generates: - requestBody schema for body-based methods (POST, PUT, PATCH) - 422 Problem Details response

Notes¶

Path params like /users/:id are emitted as /users/{id}.
ProblemDetails schema is included in components.schemas.