apigenie-generator client elixir

Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification

Generate an Elixir client on 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).

Usage

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).

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
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: 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:

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
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.

-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

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 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.

This target's support tier is Tier 2. 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.

ResultsLevel 1Level 2Level 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 yetruns before a releaseruns before a release
Was this helpful?