View Source OpenAPI.Renderer.Module (OpenAPI Generator v0.1.0-rc.0)
Default implementation for callbacks related to rendering operation and schema modules
This module contains the default implementations for:
OpenAPI.Renderer.location/2
OpenAPI.Renderer.render/2
OpenAPI.Renderer.render_default_client/2
OpenAPI.Renderer.render_moduledoc/2
OpenAPI.Renderer.render_using/2
These focus on portions of modules that may appear in both schema and operation modules.
configuration
Configuration
All configuration offered by the functions in this module lives under the output
key of the
active configuration profile. For example (default values shown):
# config/config.exs
config :oapi_generator, default: [
output: [
base_module: nil,
default_client: Client,
location: "",
operation_subdirectory: "",
operation_use: nil,
schema_subdirectory: "",
schema_use: nil
]
]
Link to this section Summary
Functions
Choose the filesystem location for the given file based on its module name and contents
Create the contents of a file in quoted Abstract Syntax Tree (AST) form
Construct the @default_client
module attribute for modules with operations
Construct the @moduledoc
portion of the file based on the file contents
Construct any use
statements that should be included in the file
Link to this section Functions
@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 theoutput
configuration, - The
schema_subdirectory
set in theoutput
configuration, and - The underscored module name (ex.
Some.Schema
becomessome/schema.ex
)
configuration
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
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
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
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).