OpenAPI

Tesla does not parse OpenAPI documents or generate client modules. It provides request values and middleware that generated or hand-written clients can use to represent OpenAPI parameter serialization.

Parameter locations

OpenAPI parameter location decides which part of the HTTP request carries a value. Tesla keeps that boundary in generated or hand-written client code: in chooses the Tesla API, while style, explode, and allowReserved become serialization options where they apply.

path and query parameters use middleware because they are transformed into the final request URL. header and cookie parameter collections produce raw header tuples before the request enters the middleware stack.

In Tesla.Middleware.Query :modern mode, values matching Tesla.OpenAPI.QueryParams definitions use OpenAPI query serialization. Other query params remain normal Tesla query params.

OpenAPI does not define a global operation flag for rejecting unknown query parameter names. When a query parameter schema uses additionalProperties, keep that as an object-valued Tesla.OpenAPI.QueryParam value. If a generated client needs a closed set of top-level query names, validate that in the generated operation module before calling Tesla.

querystring is separate from query because OpenAPI treats it as the entire query string value. It must not be mixed with normal query parameters.

Query string operations

OpenAPI in: "querystring" treats the entire query string as one value. Use Tesla.OpenAPI.QueryString for those operations instead of Tesla.OpenAPI.QueryParam:

defmodule MyApi.Operation.Search do
  alias MyApi.Client
  alias Tesla.OpenAPI.QueryString

  defstruct query_string: nil

  def handle_operation(%Client{} = client, %__MODULE__{} = operation, opts) do
    request_opts = [
      method: :get,
      url: "/search",
      query: QueryString.form!(operation.query_string),
      opts: opts
    ]

    Tesla.request(client.client, request_opts)
  end
end

Use Tesla.OpenAPI.QueryString.raw!/2 when the OpenAPI media type already produced the exact query string. Do not send Tesla.OpenAPI.QueryString through Tesla.Middleware.Query as a normal query map in :modern mode, which expects request values backed by Tesla.OpenAPI.QueryParams in Tesla.Env.private/0.

Mapping OpenAPI fields

Use the parameter location to choose the Tesla API. Then map only the serialization fields that Tesla needs at request time:

OpenAPI style names that do not belong to a parameter location are not accepted by the corresponding Tesla value object. Tesla options use Elixir atoms and snake case, so OpenAPI pipeDelimited, deepObject, and allowReserved become :pipe_delimited, :deep_object, and :allow_reserved.

schema.additionalProperties affects the value a generated client accepts for an object parameter. It does not become a Tesla.OpenAPI.QueryParam option.

For a generated-operation walkthrough, see Working with OpenAPI parameters.

For quick lookup while implementing generated clients, see the OpenAPI Cheat Sheet.