Migrating from OpenAPI.jl 0.2.x to 1.0

OpenAPI.jl 1.0 replaces the 0.2.x model — a runtime library consumed by code that the Java openapi-generator julia-client / julia-server targets produced — with a pure-Julia pipeline: OpenAPI.client and OpenAPI.server read an OpenAPI 3.0/3.1/3.2 document and emit a generated module directly. No Java toolchain is involved.

The 0.2.x runtime API (OpenAPI.Clients, OpenAPI.Servers, APIModel, val_format, …) is removed in 1.0. Code generated by openapi-generator's Julia targets does not work against OpenAPI.jl 1.0 and must stay on 0.2.x.

If you stay on the openapi-generator lane

Pin the runtime in your project's compat section:

[compat]
OpenAPI = "0.2"

The 1.0 line does not provide a compatibility bridge for these generated packages. Check the repository's current release policy before you depend on future 0.2.x backports.

If you migrate to the native generator

Regenerate from your document — the generated artifact, not this package's API, is what your code calls:

using OpenAPI
OpenAPI.client("openapi.json"; name = "MyClient", path = "MyClient.jl")
OpenAPI.server("openapi.json"; name = "MyServer", path = "MyServer.jl")

Client differences

0.2.x (openapi-generator)	1.0 (native)
Package with `api_<name>.jl`, `model_<name>.jl` files	One generated module file that uses `OpenAPI.Runtime`
`OpenAPI.Clients.Client(root; kwargs...)`	`MyClient.Client(server; kwargs...)`, or the module-wide `MyClient.DEFAULT_CLIENT` configured via `MyClient.server!`
API-set structs: `getOrderById(api::StoreApi, orderId)`	Flat module functions, lowercase of `operationId`: `MyClient.getorderbyid(orderId; client = c)`
Returns `(result, http_response)` tuple	Returns the decoded value; pass `with_http_info = true` for an `ApiResponse` (status, headers, body)
`ApiException` on errors	`ApiError` (undocumented error statuses), plus typed decode/validation errors
`pre_request_hook`, `get_return_type`	`request_headers` / `request_options` keywords; typed responses come from the document
Chunk readers (`LineChunkReader`, …) for streaming	`stream_to::Channel` keyword; framing follows the response media type, customizable with `codec!`
`httplib = Downloads` or `HTTP` backends	HTTP.jl only
Constructor/`setproperty!` validation, `val_format` overloads	Full JSON Schema validation at encode/decode time; disable per client with `validate_requests` / `validate_responses`
`mutable struct` models, `haspropertyat` / `getpropertyat`	Immutable keyword-constructed structs; optional absent fields are `ABSENT`

Server differences

The mounting contract is deliberately shaped like the 0.2.x target: implement the handler functions the generated module's header lists, then MyServer.register!(router, impl; path_prefix = "", middleware = nothing) (register remains as an alias). The four named 0.2.x middleware hooks (init, pre_validation, pre_invoke, post_invoke) are replaced by the single middleware(handler) -> handler wrapper. Handlers return the declared Julia type or a full HTTP.Response for custom behavior.

Capabilities dropped relative to the openapi-generator lane

Swagger 2.0 input. The 1.0 loader rejects Swagger 2.0 documents; convert them to OpenAPI 3.x first (openapi-generator and swagger-converter both do this).
User-overridable templates. There is no mustache layer; generation is deterministic from the document.
Per-model / per-API file layout and markdown docs. Output is a single file. Operations and models carry Julia docstrings generated from the document's summary/description fields instead of docs/*.md.

Generated artifact compatibility

Each native generated module records both its generator version and its generated-code contract version. It can use compatible runtime fixes without regeneration while the contract version stays the same. Regenerate when the load-time guard reports a contract mismatch, or when a fix changes generated source.