OpenAPI.jl

OpenAPI.jl reads OpenAPI descriptions and generates single-file, typed Julia HTTP clients and server stubs. It also provides a smaller API for creating an OpenAPI document from declared Julia endpoints.

Three pieces:

1. Client generation — OpenAPI.client turns an OpenAPI 3.0, 3.1, or 3.2 document (built in-process, read from JSON or YAML, or fetched from a running app) into a deterministic single-file Julia client. Generated modules use HTTP.jl for transport and JSON.jl plus OpenAPI's provisional schema engine for typed, validated request and response handling.
2. Server generation — OpenAPI.server turns the same documents into a deterministic single-file server-stub module: typed request decoding, response validation and encoding, and a register!(router, impl) entry point that mounts handler functions you implement onto a framework router.
3. Document generation — describe endpoints as OpenAPI.Operations and get a valid OpenAPI 3.2.0 document. Framework packages can add router adapters through the OpenAPI.operations and OpenAPI.register! extension seams.

The pipeline supports OpenAPI 3.0.x, 3.1.x, and 3.2.x. It parses JSON and YAML, resolves references, validates the document, normalizes version differences, plans Julia types, and emits deterministic source code. OpenAPI.jl supports Julia 1.10 LTS and later Julia 1.x releases.

OpenAPI.jl does not export names. Use its API through the OpenAPI namespace.

Installation

pkg> add OpenAPI

A generated module additionally imports HTTP and JSON (plus the standard libraries Base64, Dates, and UUIDs). Add those two packages to the environment that will include the generated file.

Generate a client

using OpenAPI, HTTP

OpenAPI.client(
    "https://example.com/openapi.yaml";
    name = "ExampleClient",
    path = "ExampleClient.jl",
)

include("ExampleClient.jl")

client = ExampleClient.Client("https://api.example.com")

# Each operationId becomes a Julia function. Path parameters are positional,
# other parameters are keywords.
result = ExampleClient.get_widget("widget-123"; verbose = true, client)

Generating clients covers the full calling convention, error handling, and content negotiation.

Generate a server

using OpenAPI, HTTP

OpenAPI.server(
    "https://example.com/openapi.yaml";
    framework = :HTTP,
    name = "ExampleServer",
    path = "ExampleServer.jl",
)

The generated module header lists every handler signature to implement; ExampleServer.register!(router, Handlers) mounts them on an HTTP.Router. Generating servers covers the handler contract, middleware, and request decoding behavior.

How the documentation is organized

• Migrating from 0.2.x — what changed relative to the openapi-generator lane, and how to move over.
• Generating clients, Streaming and codecs, and Security — generating a client and everything the generated client can do.
• Generating servers — server stubs, the handler contract, and register!.
• Documents from Julia code — the authoring API.
• Pipeline and diagnostics — the staged public pipeline, diagnostics, resource limits, and reference resolution.
• Generated models — how JSON Schemas become Julia types and what validation guarantees hold.
• Generated modules and the runtime contract — why generated files are versioned build products and when to regenerate.
• Support boundary — what is supported, deferred, and rejected, and what strict mode means.
• API reference — docstrings for every public name.

Specification sources

OpenAPI behavior follows the normative OpenAPI 3.0.4, OpenAPI 3.1.1, and OpenAPI 3.2.0 specifications. The files in the repository's schemas/ directory are official structural schemas published by the OpenAPI Initiative. The normative text remains authoritative when a published schema differs from it.