API reference

OpenAPI.jl: build OpenAPI documents from declared endpoints, and generate Julia clients from OpenAPI documents.

Three pieces:

1. Document generation — describe endpoints as OpenAPI.Operations and get a valid OpenAPI 3.2.0 document. Framework packages can add router adapters through the operations and register! extension seams.
2. 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.
3. 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 (HTTP.Router through the HTTP extension; other frameworks through the OpenAPI.server_source seam).

OpenAPI.load(source; options...) -> SourceDocument

Parse JSON or YAML, enforce resource limits, detect OAS 3.0/3.1/3.2, and run the official structural schema for that OAS minor line.

Return all structural diagnostics without throwing for validation errors.

OpenAPI.read(source; options...) -> AbstractDict

Read a JSON or YAML OpenAPI 3.0, 3.1, or 3.2 document. source may be inline text, a local file, or an HTTP(S) URL when HTTP.jl is loaded. The returned object is recursively read-only.

Use OpenAPI.load when source identity, format, and version metadata are also needed.

OpenAPI.parse(source; options...) -> AbstractDict

Behaves exactly like OpenAPI.read; kept for callers that expect a parse name in the namespace.

OpenAPI.validate(document) -> document

Validate an in-memory document against the official structural schema for its declared OAS 3.0, 3.1, or 3.2 minor line. This compatibility API returns the original object. Use OpenAPI.check to collect structured diagnostics.

An immutable, parsed OpenAPI source resource.

DocumentVersion(value::AbstractString)

The parsed openapi version declaration of a source document. Accepts 3.0.x, 3.1.x, and 3.2.x values, with an optional prerelease suffix, and rejects everything else. Carries raw, major, minor, patch, and prerelease fields; OpenAPI.oas_family names the minor line it belongs to.

oas_family(version::DocumentVersion) -> Symbol

The OAS minor line a document belongs to: :oas30, :oas31, or :oas32. Behavior that differs between specification lines — structural schema selection, normalization rules — follows this family, never the patch version.

location(document::SourceDocument, pointer = Resources.JSONPointer()) -> SourceLocation

The source location of the value at pointer inside a loaded document. When no position was recorded for the exact node, the nearest recorded ancestor's position is reported. Diagnostics use these locations to point back into the original JSON or YAML text.

A resource and JSON Pointer location inside an OpenAPI description.

A one-based source position when a parser can report one.

One stable, machine-readable OpenAPI diagnostic.

An error that contains all diagnostics collected for one operation.

OpenAPI.normalize(source; options...) -> NormalizedAPI

Load, resolve, and normalize an OpenAPI 3.0, 3.1, or 3.2 description into a stable intermediate representation. Strict mode rejects undefined Path Item reference sibling behavior and all semantic errors before code generation.

The immutable, version-neutral result of OpenAPI.normalize: resolved references, a frozen resource registry, and normalized servers, security schemes, schemas, and operations, together with the diagnostics produced while normalizing. OpenAPI.plan and OpenAPI.serverplan consume this value.

Build the deterministic Julia model and operation plan used by code generation.

The result of OpenAPI.plan: the deterministic Julia model and operation plans for one generated client module, plus the diagnostics produced while planning. Pass it to OpenAPI.client to emit source.

OpenAPI.client(source; name="ApiClient", path=nothing, strict=true, options...) -> String

Generate a deterministic Julia client module after full OpenAPI loading, reference binding, semantic normalization, and type planning. The generated module supports OpenAPI 3.0, 3.1, and 3.2 request/response models, parameter styles, content negotiation, and security requirements.

datetime = :utc (the default) maps format: date-time to Dates.DateTime and normalizes RFC 3339 offsets to UTC while decoding; datetime = :zoned maps to TimeZones.ZonedDateTime and preserves offsets, making the generated module depend on TimeZones.jl.

OpenAPI.serverplan(source; name="ApiServer", strict=true, options...) -> ServerPlan

Build the deterministic Julia model and operation plan used by server stub generation. Accepts the same sources and options as OpenAPI.plan and additionally rejects documents whose requests cannot be decoded faithfully on the server side.

The result of OpenAPI.serverplan: the deterministic Julia model and operation plans for one generated server-stub module, plus the diagnostics produced while planning. Pass it to OpenAPI.server to emit source.

OpenAPI.server(source; framework=:HTTP, name="ApiServer", path=nothing, strict=true, options...) -> String

Generate a deterministic Julia server-stub module after full OpenAPI loading, reference binding, semantic normalization, and type planning. The generated module decodes typed request parameters and bodies, dispatches to handler functions you implement (one per operation, listed in the generated header), validates and encodes responses, and mounts on the chosen framework's router through its register!(router, impl) function.

framework selects the emitter: :HTTP (available when HTTP.jl is loaded) targets HTTP.Router; server framework packages can add their own through the OpenAPI.server_source extension seam. Accepts the same source values and keyword options as OpenAPI.client.

OpenAPI.server_source(::Val{framework}, plan::ServerPlan) -> String

Extension seam for framework-specific server-stub emission. Loading HTTP.jl adds the Val{:HTTP} method; server framework packages such as Servo.jl add their own. OpenAPI.server dispatches here.

OpenAPI.server_module_source(plan; imports, glue) -> String

Assemble a generated server module for a framework extension: the shared generated runtime, models, operation descriptors, and the _SERVER_OPS route table, wrapped between the extension's imports line and its router glue source. Framework extensions must call this from their OpenAPI.server_source methods so the generated module includes the current contract guard. Most applications call OpenAPI.server instead.

OpenAPI.document(operations; title="API", version="0.1.0", description="", servers=String[])
    -> JSON.Object

Build a valid OpenAPI 3.2.0 document from a vector of Operations. Named struct types encountered in parameter, body, and response types are collected under components/schemas and referenced by $ref. Serialize with JSON.json(doc) (or JSON.json(doc; pretty=2)).

Framework packages can add router-specific methods without becoming an OpenAPI dependency.

OpenAPI.Operation(; id, method, path, kw...)

A framework-neutral description of one endpoint, the input to OpenAPI.document. Anything that can describe its endpoints as Operations can use the same document-generation path.

Keywords:

• id::String — the operationId (also the generated client's function name)
• method::Symbol — :GET, :POST, … ((:GET, :POST, :PUT, :DELETE, :PATCH, :HEAD, :OPTIONS, :TRACE, :QUERY))
• path::String — /segment/{param} template; placeholders must match the :path params exactly
• summary="" — human description
• params=Param[] — path/query parameters
• bodytype=nothing — Julia type of the request body, or nothing for none
• responsetype=nothing — no success response body (status 200); the type Nothing means 204 No Content, Any means unconstrained JSON, and a Union{Nothing, T} emits both 204 and a 200 with T's schema
• contenttype="application/json" — media type for body/response content
• secured=false — whether the operation requires authentication (emitted as a bearer security requirement)

OpenAPI.Param(name, location, type; required=true)

One path or query parameter of an Operation: location is :path or :query, type is the Julia type the value coerces to (drives the emitted schema).

Accumulates #/components/schemas entries while a document is built. Named Julia struct types are registered once (by nameof, deduped) and referenced.

schemaof(registry, T) -> JSON.Object

The JSON Schema for a Julia type. Primitives map directly; Unions become oneOf (with Union{Nothing, T} including a null schema); Vector/Dict map to arrays/objects; NamedTuples become inline object schemas; named structs are registered in the components registry and referenced with $ref; Any and abstract types become the empty (match-anything) schema.

obj(pairs::Pair...) -> JSON.Object{String,Any}

An ordered JSON object from key-value pairs; keys convert to String. A small helper for assembling OpenAPI document fragments by hand alongside OpenAPI.document.

OpenAPI.register!(integration; kwargs...)

Extension seam for downstream server frameworks that expose a generated OpenAPI document. OpenAPI.jl itself does not depend on a server framework.

Extension seam for converting framework routes to Vector{Operation}.

Internal JSON Schema resource, compilation, rebasing, and validation support.

This module is isolated from OpenAPI-specific semantics so it can move to JSONSchema.jl after the implementation and API have hardened. Generated clients use it through OpenAPI.SchemaEngine; it is not a general-purpose exported API.

Generic, non-mutating JSON resource identification and lookup.

Runtime support for generated OpenAPI clients.

Generated client modules import this module's machinery instead of carrying a pasted copy: protocol encoding and decoding, parameter styling, content negotiation, multipart bodies, security schemes, and the HTTP request core. Each generated module packages its document-specific data — compiled schema resources, security schemes, and the default server — into a Spec that its Client values carry.

Version of the contract between this runtime and generated modules: the names generated code imports, the shapes of the data it bakes (Spec keywords, operation tables, schema descriptors, dialect literals), and their semantics. Bump this whenever any of those change so previously generated modules fail loudly at load time instead of misbehaving; see require_contract.

Runtime.require_contract(version::Integer, generator::AbstractString)

Called at load time by every generated module to assert that the loaded runtime still provides the contract the module was generated against; generator records the OpenAPI.jl version that produced the module. Throws with regeneration guidance on mismatch. This function and CONTRACT_VERSION are permanently stable names: renaming either would make old generated modules fail with a bare UndefVarError instead of this error.

Document-specific data a generated module supplies to the shared runtime: schema resources for validation, security schemes, and server defaults. Mutable runtime state (the module-wide server override and the compiled schema-graph cache) lives here so independent generated modules never share or clobber each other's state.