---
url: /httpx.zig/guide/openapi.md
---
# OpenAPI Guide

HTTPX provides automatic OpenAPI 3.1.0 specification generation, route documentation, schema reflection, and built-in interactive documentation UIs (Swagger UI, ReDoc, Scalar).

## Overview

Define metadata alongside your routes. HTTPX aggregates all routes, parameters, request bodies, and responses into a single canonical OpenAPI specification.

```zig
const std = @import("std");
const httpx = @import("httpx");

pub fn main() !void {
    var gpa: std.heap.DebugAllocator(.{}) = .init;
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();
    const io = std.Io.Threaded.global_single_threaded.io();

    var server = try httpx.Server.init(allocator, io, .{
        .port = 8080,
        .enableDocs = true,
        .docs = .{
            .title = "Users API",
            .version = "1.0.0",
            .description = "Production API built with HTTPX",
        },
    });
    defer server.deinit();

    server.run();
```

## Documentation UIs

* **Swagger UI** (`/docs`): Interactive API explorer with "Try It Out" request execution.
* **ReDoc** (`/redoc`): Three-panel responsive documentation focused on readability and schemas.
* **Scalar** (`/scalar`): Modern, sleek API reference with dark mode and client code snippets.

All three UIs consume the exact same canonical `/openapi.json` definition generated by HTTPX.

## Related

* [Web: OpenAPI](/web/openapi)
* [Web: Documentation UIs](/web/documentation-ui)
* [Example: OpenAPI Server](/examples/openapi)