Skip to content

MIGRATION.md

Latest commit

 

History

History
81 lines (64 loc) · 4.65 KB

MIGRATION.md

File metadata and controls

81 lines (64 loc) · 4.65 KB
Raw

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
Client(url; escape_path_params = false) Declare allowReserved: true on the path parameter in the document; the generated client then leaves reserved characters such as / unescaped for that parameter. Requires a 3.0 or 3.2 document — 3.1 scopes allowReserved to query parameters and rejects it on a path parameter at load time
pre_request_hook rewriting the path to send %2E for . Client(url; escape_path_chars = ".") percent-encodes the listed characters in every path parameter value on top of the standard RFC 3986 escaping
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.