OpenAPI Reference

Overview

Zigmund automatically generates an OpenAPI 3.1 specification from registered routes, parameter markers, security schemes, and route options. This page documents the types used to customize and extend the generated specification.

OpenApiSchema

Describes a JSON Schema for use in OpenAPI request/response definitions.

pub const OpenApiSchema = struct {
    schema_type: []const u8 = "string",
    schema_format: ?[]const u8 = null,
    is_array: bool = false,
    fields: []const OpenApiSchemaField = &.{},
    one_of: []const OpenApiSchema = &.{},
    any_of: []const OpenApiSchema = &.{},
    all_of: []const OpenApiSchema = &.{},
    discriminator_property_name: ?[]const u8 = null,
    discriminator_mapping: []const OpenApiDiscriminatorMapping = &.{},
};

OpenApiSchemaField

Describes a single field within an object schema.

OpenApiDiscriminatorMapping

Maps a discriminator value to a schema reference.

ResponseSpec

Declares additional response specifications for a route.

OpenApiExample

Provides named examples for parameters or request/response bodies.

OpenApiResponseExamples

Groups examples for a specific response status code.

OpenApiExtension

Adds vendor extension fields (x- prefixed) to the specification.

OpenApiCallback

Defines an OpenAPI callback (webhook triggered by the API).

OpenApiWebhook

Defines an OpenAPI webhook (external event notification).

OpenApiSecurityRequirement

Specifies a security scheme and its required scopes.

OpenApiSecurityAlternative

Groups security requirements as alternatives (logical OR).

Accessing the Generated Spec

const spec_json = try app.openapi();

The result is cached and invalidated automatically when routes or security schemes change.

Example

try app.post("/items", createItem, .{
    .summary = "Create an item",
    .response_model = ItemResponse,
    .status_code = .created,
    .responses = &.{
        .{ .status_code = .conflict, .description = "Item already exists" },
    },
    .openapi_request_examples = &.{
        .{
            .name = "basic",
            .summary = "Basic item",
            .value_json = "{\"name\":\"Widget\",\"price\":9.99}",
        },
    },
    .openapi_callbacks = &.{
        .{
            .name = "onItemCreated",
            .expression = "{$request.body#/callback_url}",
            .summary = "Notify when item is created",
        },
    },
});