@spec filename(OpenAPI.Renderer.State.t(), OpenAPI.Renderer.File.t()) :: String.t()

Choose the filesystem location for the given file based on its module name and contents

Default implementation of OpenAPI.Renderer.location/2.

If the file does not contain any operations, the file name is chosen as the concatenation of:

• The base location set in the output configuration,
• The schema_subdirectory set in the output configuration, and
• The underscored module name (ex. Some.Schema becomes some/schema.ex)

Configuration

Use output.location to set the directory of all outputted files (ex. lib). Then, optionally split operations and schemas into separate directories using output.operation_subdirectory and output.schema_subdirectory. This can be useful to show which modules are generated vs. those that are written by hand.

config :oapi_generator, default: [
  output: [
    location: "lib",
    operation_subdirectory: "operations",
    schema_subdirectory: "schemas"
  ]
]

With this configuration, an schema module named My.ExampleSchema would be output to lib/schemas/my/example_schema.ex.

@spec render(OpenAPI.Renderer.State.t(), OpenAPI.Renderer.File.t()) :: Macro.t()

Create the contents of a file in quoted Abstract Syntax Tree (AST) form

Default implementation of OpenAPI.Renderer.render/2.

This callback is the primary function called to render a file. It makes use of several other callbacks of the renderer (in this order), each of which my be overridden separately:

• OpenAPI.Renderer.render_moduledoc/2
• OpenAPI.Renderer.render_using/2
• OpenAPI.Renderer.render_default_client/2
• OpenAPI.Renderer.render_schema/2
• OpenAPI.Renderer.render_operations/2

Besides concatenating the results of these functions, this function also writes the defmodule call itself.

Configuration

Use output.base_module to determine a prefix to the name of all modules created by the generator. For example, given the following configuration:

config :oapi_generator, default: [
  output: [
    base_module: MyClientLibrary
  ]
]

A file with module name MySchema would be output as MyClientLibrary.MySchema. Usually, this configuration contains the name of your library's root module.

@spec render_default_client(OpenAPI.Renderer.State.t(), OpenAPI.Renderer.File.t()) ::
  Macro.t()

Construct the @default_client module attribute for modules with operations

Default implementation of OpenAPI.Renderer.render_default_client/2.

This allows callers to override the client implementation without having to pass the default module in as an argument. This callback renders the definition of the @default_client module attribute, effectively choosing which module will be called for every operation.

Configuration

Use output.default_client to choose which module is set. A value of false or nil will cause the module attribute not to be set at all, which may cause compilation errors if using the default implementation of the operation function renderer.

config :oapi_generator, default: [
  output: [
    default_client: MyLib.MyClient
  ]
]

This will result in a statement @default_client MyLib.MyClient to be added to any module that contains operations. Note that the output.base_module configuration is not used in this case.

If the configuration is unset, then a default module of [base module].Client will be used, based on the output.base_module configuration.

@spec render_moduledoc(OpenAPI.Renderer.State.t(), OpenAPI.Renderer.File.t()) ::
  Macro.t()

Construct the @moduledoc portion of the file based on the file contents

Default implementation of OpenAPI.Renderer.render_moduledoc/2.

This function provides a basic moduledoc for each file. If the file contains only schemas, then the moduledoc focuses on the structs and types it provides:

Provides struct and types for a MySchema

If the file contains operations, it focuses on those:

Provides API endpoints related to MyOperations

@spec render_using(OpenAPI.Renderer.State.t(), OpenAPI.Renderer.File.t()) :: Macro.t()

Construct any use statements that should be included in the file

Default implementation of OpenAPI.Renderer.render_using/2.

Another route for customization of the outputted code is via meta-programming. This callback enables library authors to use any module they like at the top of files that contain schemas, operations, or both. The referenced modules can then perform additional compile-time changes.

Configuration

Use output.operation_use to include a use statement at the top of each file that contains any operations, and output.schema_use to similarly include a use statement at the top of files containing a schema. Keep in mind that some files may contain both operations and a schema.

config :oapi_generator, default: [
  output: [
    schema_use: MyLib.Schema
  ]
]

This will result in a statement use MyLib.Schema (note that the output.base_module configuration is not used in this context).