# apigenie-generator client elixir

Source: https://apigenie.pl/docs/reference/generator/client-elixir
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client go](https://apigenie.pl/docs/reference/generator/client-go-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 2](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate an Elixir client on [Req](https://hexdocs.pm/req) from an OpenAPI document.

From an AsyncAPI document, the command generates a WebSocket and Kafka client library instead; see
[`apigenie-generator client elixir` (AsyncAPI)](/docs/reference/generator/client-elixir-asyncapi).

## Usage

```sh
apigenie-generator client elixir [...OPTIONS] INPUT_FILE
```

## Description

The generator writes a Mix project (Elixir 1.18 or later) depending on Req 0.5 or later and Jason.
Its code passes `mix format --check-formatted`, `mix compile --warnings-as-errors`,
`mix credo --strict` and `mix dialyzer`.

The input must be an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see
[Swagger 2.0 input](/docs/reference/generator#swagger-20-input)).

| File | Contents |
| ---- | -------- |
| `lib/<app>.ex` | the root module, with `new/1` creating a client |
| `lib/<app>/api/<tag>.ex` | a module per tag (`Default` for operations without tags), with a function per operation |
| `lib/<app>/models/*.ex` | a module per schema: structs, enums, unions and aliases, with `new/1`, `new!/1` and `to_map/1` |
| `lib/<app>/client.ex`, `api_error.ex` | the client struct and the error of operations |
| `lib/<app>/metadata.ex` | the servers and the security schemes of the document |
| `lib/<app>/runtime/*.ex`, `models/decode.ex`, `models/encode.ex` | the encoding of parameters and bodies, and the decoding of responses |
| `mix.exs`, `.formatter.exs`, `.gitignore`, `README.md` | the project |

```elixir
client =
  CarpetExpress.new(
    base_url: "https://api.example.com/v2",
    auth: [bearer_jwt: System.fetch_env!("API_TOKEN")],
    req_options: [receive_timeout: 10_000, retry: :transient]
  )

{:ok, shipment} = CarpetExpress.Api.Shipments.get_shipment(client, shipment_id: "shp_123")
shipment = CarpetExpress.Api.Shipments.get_shipment!(client, shipment_id: "shp_123")
```

### Functions

Every operation is a function named after its `operationId` in snake_case, in the module of its
first tag:

- `op(client, params \\ [], opts \\ [])`, or `op(client, body, params \\ [], opts \\ [])` when the
  operation has a request body;
- `params` is a keyword list of the path, query, header and cookie parameters, keyed by their
  names in snake_case (`shipment_id: "..."`, `if_match: ...`); missing required parameters and
  unknown ones give an error before anything is sent;
- `opts` are the options of the call: `:content_type` (the media type of the body when the
  operation accepts several), `:headers` and `:req_options` (options of `Req.request/2`, e.g.
  `retry: false` or `into: File.stream!("label.pdf")`).

A `!` variant of each function returns the body itself and raises the error.

### Responses and errors

A response with a 2XX status gives `{:ok, body}`: the body decoded into its model (`new/1` of
its module), a list of them, a string for `text/*` media types, the bytes for other media types,
or `nil` without content. Any other status gives `{:error, %ApiError{reason: :status}}`, with the
`status`, the `headers` and the decoded `body` (a problem document, the error's model). The other
reasons are `:transport` (the request failed), `:decode` (the body doesn't match its schema),
`:params` and `:auth`.

Since 0.12.0, a `text/event-stream`, JSON Lines (`application/jsonl`, `application/x-jsonlines`,
`application/x-ndjson`, `application/ndjson`) or `application/json-seq` response gives `{:ok,
stream}`, a lazy stream of its items. Each item is decoded as it arrives. A JSON Lines or JSON text
sequence item is a JSON value, decoded with the `itemSchema` of the media type (OpenAPI 3.2) when
there is one. An event is the map of its fields, with the string keys `"data"` (its lines joined),
`"event"`, `"id"` and `"retry"` (an integer); an event without a `data` field isn't an item. An
`itemSchema` decodes that map, into its model when the schema is an object. Without an `itemSchema`,
the item is the map. Such operations are sent with `into: :self` and `compressed: false` unless
`:req_options` sets `:into`.

Enumerating the stream raises `<App>.Models.Decode.Error` for an item that doesn't match the
`itemSchema`, and `JSON.DecodeError` for a line that isn't JSON. Enumerate it in the process that
made the call.

### Parameters and bodies

Parameters are encoded in their styles: `simple`, `label` and `matrix` path parameters, `form`,
`spaceDelimited`, `pipeDelimited` and `deepObject` query parameters, headers, cookies, and
parameters described with `content` as JSON. Models, enums (atoms), dates and times are encoded
with their schemas.

| Media type | Body |
| ---------- | ---- |
| JSON (`application/json`, `*+json`) | a model struct or a plain map |
| `application/x-www-form-urlencoded` | a model struct or a map, its fields in the styles of their `encoding` |
| `multipart/form-data` | a map or a keyword list of the parts: files as `{content, filename: ..., content_type: ...}` or the content alone, lists of files, values and JSON parts |
| `text/event-stream`, JSON Lines, `application/json-seq` | since 0.12.0, an enumerable of items, each encoded with the `itemSchema` and sent as it is enumerated |
| `text/*` | a string |
| anything else | iodata, or an enumerable of chunks |

### Servers

The base URL is the first server of the document, or the `:base_url` option of `new/1`.
Operations with servers of their own are sent there, unless `operation_servers: false`.

### Security

`new/1` takes the credentials by security scheme in `:auth`, keyed by the scheme names in
snake_case (`CarpetExpress.Metadata.security_schemes/0` lists them). A credential is the value
(an API key, a token, `{user, password}` for HTTP basic) or a supplier called before each request
(`fn -> {:ok, token} end`, or `{module, function, args}`), e.g. to fetch and refresh OAuth2 tokens.
Each request uses the first security requirement of its operation whose schemes all have a
credential: API keys in headers, the query or cookies, HTTP bearer and basic, OAuth2 and OpenID
Connect tokens as bearer tokens. Mutual TLS is set up with `req_options: [connect_options:
[transport_opts: [certfile: ..., keyfile: ...]]]`.

### Types

The models are the modules of [the Elixir models](/docs/reference/generator/client-elixir#types):
a struct per object (with `allOf` flattened), atoms for string enums, a module dispatching on the
discriminator for `oneOf` and `anyOf`, `Date`, `DateTime`, `NaiveDateTime` and `Time` for dates and
times, binaries for `format: byte` (decoded from base64) and `format: binary`,
`additional_properties` maps, and `| nil` for nullable values.

Since 0.12.0, the models check the constraints of the schemas: `minLength`, `maxLength` and
`pattern`, `minimum`, `maximum`, their exclusive forms and `multipleOf`, `minItems`, `maxItems`
and `uniqueItems`, `minProperties` and `maxProperties`. `new/1` and the decoding of responses
check them; a response that breaks one gives `{:error, %ApiError{reason: :decode}}`. A struct
built as a literal is sent unchecked.

`prefixItems` are Elixir tuples when the array is closed (`items: false`), `minItems` requires
every position, and each position is a scalar, an enum or a model, not nullable, with types short
enough for the tuple's type to fit on one line (60 characters). Otherwise they are lists whose
first items are checked against the positions. The entries whose keys match `patternProperties`
are in the `additional_properties` map, each checked with the schema of its pattern.
`if`/`then`/`else`, `dependentRequired` and `dependentSchemas` are checked between the properties
of a struct when they only test the presence and the values of properties.

Since 0.12.0, `readOnly` properties are left out of request bodies and `writeOnly` properties
ignored in responses. Neither is a required field of the struct.

### Extensions

| Extension | Effect |
| --------- | ------ |
| `x-apigenie.codegen.name` | name of the module of a component schema, unless `module_overrides` names it |
| `x-apigenie.codegen.action-name` | name of the function of an operation without an `operationId` (with the default `action_naming`, which lists `id` first) |
| `x-apigenie.codegen.disabled` | `true` on an operation or its path item leaves the operation out |
| `x-internal` | `true` on an operation or its path item leaves the operation out, unless `internal_operations` is set |
| `x-defaultMapping` | `defaultMapping` of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn't mapped |

The extensions can live in an overlay for this target instead of in the document, e.g.
`elixir.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: Elixir names
  version: 1.0.0
actions:
  - target: $.components.schemas.Pet
    update:
      x-apigenie:
        codegen:
          name: Animal
  - target: $.paths['/admin']
    update:
      x-internal: true
```

```sh
apigenie-generator client elixir openapi.yaml --overlay elixir.overlay.yaml -o out
```

### Limitations

- Links aren't generated, and neither are receivers of callbacks and webhooks (`server phoenix`
  generates their senders).
- Conditions between properties that test more than their presence and values (a `pattern` in an
  `if` schema, for example) aren't checked.
- A `pattern` that Elixir's `Regex` doesn't compile matches every string. The value isn't checked,
  and in `patternProperties` that pattern's schema checks every key no earlier pattern matches.
- A property matching several `patternProperties` is checked against the first pattern only.

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.client_elixir.overlay` in the configuration file (with paths
relative to it). Warnings and errors about a value an overlay set point to the overlay. Not for a
`.proto` input.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Directory where the project is generated.

### --package-name

Name of the Mix application, converted to snake_case (`carpet-express` gives `carpet_express`
and the root module `CarpetExpress`). Defaults to the name of the output directory.

### --package-version

Version of the Mix project; `0.1.0` by default.

### -p, --property NAME=VALUE

Sets a generator option (see below), e.g. `-p dev_deps=false`. Options given on the command line
take precedence over the configuration file. Lists are comma-separated (`-p include_tags=pets,store`)
and mappings too (`-p module_overrides=pet-owner=Owner`).

## Configuration

```yaml
version: '1.0'
commands:
  generate:
    client_elixir:
      app: carpet_express
      namespace: CarpetExpress
      exclude_tags: [internal]
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `app` | string | name of the output directory | Name of the Mix application (snake_case, the directory under `lib/`); also set by `--package-name`. |
| `namespace` | string | the application in PascalCase | Root module of the generated modules, e.g. `CarpetExpress`. |
| `include_tags` | list of strings | | Generates only the operations with one of these tags. |
| `exclude_tags` | list of strings | | Skips the operations with one of these tags. |
| `skip_prune` | boolean | `false` | Keeps the component schemas that no generated operation uses. |
| `internal_operations` | boolean | `false` | Also generates the operations marked `x-internal: true`. |
| `dev_deps` | boolean | `true` | Lists credo and dialyxir as dependencies of `mix.exs` (`only: :dev`). |
| `action_naming` | list of `id`, `extension`, `url` | `id, extension, url` | Where function names come from, in order of preference. |
| `field_prefix` | string | `field_` | Prefix of struct fields whose property names give no valid name. |
| `module_overrides` | map of strings | | Module names of component schemas, e.g. `pet-owner: Owner`. |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#openapi).

This target's support tier is [Tier 2](/docs/reference/generator/conformance#tiers). It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0 | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yet | ✓ pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) | ✓ 37 of 37 operations pass (elixir) |
| Development version | ✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yet | runs before a release | runs before a release |
