Configuration for the code generator

configuration

Configuration

This section is an overview of the available configuration options. For a more in-depth discussion of output module naming, see Naming below. See also type t:t() below for the exact type specification of each option.

• base_location (string, required): Relative path (from the base of the Mix project where the code generator is run) to output files. When creating a standalone client library, this will often be lib/.

• base_module (module, required): Base module for all output files. For example, a base module of Example will output schemas like Example.MySchema and operation files like Example.MyOperations. When outputting a standalone client library, this will often be the base module of the library.

• default_client (module): Module to call when making a web request. This code generator has no opinion on how HTTP requests are made. Instead, you must provide a client module that implements a request/1 function and performs the request and decodes the response. By default, a module [base_module].Client will be used.

• group (list of modules): Namespaces to use when grouping modules. For example, two schemas SchemaOne and SchemaTwo grouped by the Schema module would become Schema.One and Schema.Two. Defaults to no grouping.

• ignore (list of modules, strings, or regular expressions): Schemas to ignore when outputting well-defined Elixir structs. Schemas that are ignored will be replaced with a map type when referenced elsewhere in the code. When provided as a module or string, the ignore pattern must exactly match the name of the schema after any merges. Defaults to no schemas ignored.

• merge (list of two-tuples): Source and destination modules for schemas that should be merged into a single file. See Merging below for examples. Defaults to no schemas merged.

• operation_location (string): Relative path, after the base_location, to output operation files. This may useful if you want to hide generated operation files in a subdirectory of a larger project. Defaults to outputting operation files to the base_location.

• rename (list of rename pattern and action tuples): Renaming actions to take on schema names. The two elements of each tuple will be fed as the second and third arguments to String.replace/4 along with the schema name. See Renaming below for examples. Defaults to no schemas renamed.

• schema_location (string): Relative path, after the base_location, to output schema files. This may useful if you want to hide generated schema files in a subdirectory of a larger project. Defaults to outputting schema files to the base_location.

• types (keyword list): Overrides to the types defined by the generator. Each value should be a tuple {module, type} such as {MyModule, :t}.

  • error: Override the error type for all operations. APIs often define their own error schemas, which may differ between operations. Use this option to define a single, consistent error type for all operations. For example, a value {MyError, :t} would cause operations to return {:ok, ...} | {:error, MyError.t()}.

naming

Naming

Most of the configuration of this project relates to the manipulation of schema names. It is important to understand the order of operations. As an example, imagine an OpenAPI description has the following schemas:

• #/components/schemas/simple-user
• #/components/schemas/user
• #/components/schemas/user-preferences

And the following configuration:

config :oapi_generator, default: [
  base_location: "lib/",
  base_module: Example,
  group: [User],
  ignore: [],
  merge: [{"SimpleUser", "User"}]
  rename: [{~r/Preferences/, "Settings"}]
]

In this case, naming would proceed as follows:

1. Schemas in the OpenAPI descriptions are turned into Elixir modules:

   #/components/schemas/simple-user       =>  SimpleUser.t()
   #/components/schemas/user              =>  User.t()
   #/components/schemas/user-preferences  =>  UserPreferences.t()

2. Merge settings are applied based on the original names of the schemas:

   SimpleUser.t()  =>  User.simple()

3. Ignore settings are applied based on the merged module names (no changes in this example).

4. Rename settings are applied based on the merged module names:

   UserPreferences.t()  =>  UserSettings.t()

5. Group settings are applied based on the renamed module names:

   UserSettings.t()  =>  User.Settings.t()

6. The base module is applied to get the final names:

   User.simple()      =>  Example.User.simple()
   User.t()           =>  Example.User.t()
   User.Settings.t()  =>  Example.User.Settings.t()

All of the schemas are then written to appropriate files based on the base_location and schema_location settings. Note that User.simple() and User.t() will end up in the same file as a result of the merge, sharing the same struct for their responses (with distinct typespecs).

merging

Merging

OpenAPI descriptions may have multiple schemas that are closely related or even duplicated. Merging gives the power to consolidate these schemas into a single struct that is easy to use.

For example, the GitHub API description has schemas repository, full-repository, and nullable-repository. While the "full" repository adds additional properties, the "nullable" variant is just that: all of the same properties, but the schema is nullable. This kind of oddity in the OpenAPI specification is exactly what makes most generated code difficult to use.

The following merge settings would help clean this up:

merge: [
  {"FullRepository", "Repository"},
  {~r/^Nullable/, ""}
]

In the first line, we tell the generator to merge FullRepository into Repository (the original module names based on the names of the schemas). Because the destination module appears at the end of the original module, the word "Repository" will be dropped from the type:

FullRepository => Repository :: Repository.full()

This renaming of the type is automatic for prefixes and suffixes. If no overlap is found, then the full (underscored) schema name will be used for the type:

SimpleUser        => User        :: User.simple()
PullRequestSimple => PullRequest :: PullRequest.simple()
MySchema          => Unrelated   :: Unrelated.my_schema()

If the destination module is later renamed or grouped, the merged schemas will processed in the same way.

collapsing

Collapsing

In the second line of the configuration above, we merge two nearly-identical schemas NullableRepository and Repository. Because these schemas have the same fields, there will not be a Repository.nullable() type generated; instead, references will use Repository.t(). Despite this deduplication, other parts of the code will continue to know that the original schema had nullable: true and respond accordingly.

ignoring

Ignoring

Sometimes, schemas are best treated as plain maps. In these cases, they can be ignored using a regular expression, exact string, or exact module:

ignore: [
  ~r/^Unnecessary/,
  "SomeSchema",
  AnotherSchema
]

Any references to an ignored schema will be replaced with a map() type.

grouping

Grouping

Schemas in an OpenAPI description can have extensively long names. For example, GitHub has a schema called actions-cache-usage-by-repository. Along with all other actions-related schemas, we can cut down the top-level module namespace by grouping on Actions or even further:

group: [
  Actions,
  Actions.CacheUsage
]

Even simple renaming and groups can take a raw OpenAPI description and turn it into a library that feels friendly to users.