View Source OpenAPI.Renderer behaviour (OpenAPI Generator v0.1.0-rc.0)
Phase three of code generation
The render phase begins with operation and schema structs created during the process phase. It uses this data to construct and save files containing Elixir source code. Most of the work done by this phase involves the manipulation of Elixir ASTs.
Link to this section Summary
Callbacks
Convert the Abstract Syntax Tree (AST) form of the file into formatted code
Choose the filesystem location for a rendered file to be written
Create the contents of a file in quoted Abstract Syntax Tree (AST) form
Render the @default_client
module attribute in an operation module
Render the @moduledoc
portion of the file
Render the associated types, docstring, typespec, and function for a single operation
Render the @doc
portion of an operation function
Render the main function portion of an operation
Render the @spec
portion of an operation function
Render the associated types, docstring, typespec, and function for all operations
Render the types, struct, and field function for schemas not related to an operation
Render a function __fields__/1
that return a keyword list of schema fields and their types
Render the defstruct
call for the schema types contained in the file
Render the typespecs for schema types contained in the file
Render one or more use
statements to include in the file
Write a rendered file to the filesystem
Link to this section Callbacks
@callback format(state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t()) :: iodata()
Convert the Abstract Syntax Tree (AST) form of the file into formatted code
This callback can expect a OpenAPI.Renderer.File.t/0
struct with the completed contents of
the file included in the ast
field. Nodes of the AST may include optional formatting metadata
(ex. delimiter
, indentation
, or end_of_expression
). It is recommended that the formatter
adhere to the standard configuration of the default Mix formatter (for example, formatting to a
line width of 98) in order to avoid a large amount of changes should someone run mix format
on
the generated code.
The return value of the callback can be iodata
(strings do not need to be concatenated), and
it will be stored in the contents
field of the file.
See OpenAPI.Renderer.Util.format/2
for the default implementation.
@callback location(state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t()) :: String.t()
Choose the filesystem location for a rendered file to be written
See OpenAPI.Renderer.Module.filename/2
for the default implementation.
@callback render(state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t()) :: Macro.t()
Create the contents of a file in quoted Abstract Syntax Tree (AST) form
This callback is the primary function called to render a file. The default implementation calls several other callbacks, 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
See OpenAPI.Renderer.Module.render/2
for the default implementation.
@callback render_default_client( state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t() ) :: Macro.t()
Render the @default_client
module attribute in an operation module
When using the default operation function renderer, every operation function includes a line:
client = opts[:client] || @default_client
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.
See OpenAPI.Renderer.Module.render_default_client/2
for the default implementation.
@callback render_moduledoc( state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t() ) :: Macro.t()
Render the @moduledoc
portion of the file
Users of a client library may lean on this documentation to find the operation or schema they need. While the default implementation presents a fairly basic line of documentation depending on whether the file contains operations or a schema, custom implementations of this callback could provide rich and helpful instructions to consumers.
See OpenAPI.Renderer.Module.render_moduledoc/2
for the default implementation.
@callback render_operation( state :: OpenAPI.Renderer.State.t(), operation :: OpenAPI.Processor.Operation.t() ) :: Macro.t()
Render the associated types, docstring, typespec, and function for a single operation
The default implementation of this function calls several other callbacks (all named
render_operation_*
) which can be overridden individually.
See OpenAPI.Renderer.Operation.render/2
for the default implementation.
@callback render_operation_doc( state :: OpenAPI.Renderer.State.t(), operation :: OpenAPI.Processor.Operation.t() ) :: Macro.t()
Render the @doc
portion of an operation function
See OpenAPI.Renderer.Operation.render_doc/2
for the default implementation.
@callback render_operation_function( state :: OpenAPI.Renderer.State.t(), operation :: OpenAPI.Processor.Operation.t() ) :: Macro.t()
Render the main function portion of an operation
See OpenAPI.Renderer.Operation.render_function/2
for the default implementation.
@callback render_operation_spec( state :: OpenAPI.Renderer.State.t(), operation :: OpenAPI.Processor.Operation.t() ) :: Macro.t()
Render the @spec
portion of an operation function
See OpenAPI.Renderer.Operation.render_spec/2
for the default implementation.
@callback render_operations( state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t() ) :: Macro.t()
Render the associated types, docstring, typespec, and function for all operations
This is the primary function called to render all operations in a file. The default
implementation calls several other callbacks (all named render_operation*
) which can be
overridden individually.
See OpenAPI.Renderer.Operation.render_all/2
for the default implementation.
@callback render_schema( state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t() ) :: Macro.t()
Render the types, struct, and field function for schemas not related to an operation
This is the primary function called to render schemas. The default implementation calls several
other callbacks (all named render_schema_*
) which can be overridden individually.
See OpenAPI.Renderer.Schema.render/2
for the default implementation.
@callback render_schema_field_function( state :: OpenAPI.Renderer.State.t(), schemas :: [OpenAPI.Processor.Schema.t()] ) :: Macro.t()
Render a function __fields__/1
that return a keyword list of schema fields and their types
See OpenAPI.Renderer.Schema.render_field_function/2
for the default implementation.
@callback render_schema_struct( state :: OpenAPI.Renderer.State.t(), schemas :: [OpenAPI.Processor.Schema.t()] ) :: Macro.t()
Render the defstruct
call for the schema types contained in the file
See OpenAPI.Renderer.Schema.render_struct/2
for the default implementation.
@callback render_schema_types( state :: OpenAPI.Renderer.State.t(), schemas :: [OpenAPI.Processor.Schema.t()] ) :: Macro.t()
Render the typespecs for schema types contained in the file
See OpenAPI.Renderer.Schema.render_types/2
for the default implementation.
@callback render_using( state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t() ) :: Macro.t()
Render one or more use
statements to include in the file
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.
See OpenAPI.Renderer.Module.render_using/2
for the default implementation.
@callback write(state :: OpenAPI.Renderer.State.t(), file :: OpenAPI.Renderer.File.t()) :: :ok
Write a rendered file to the filesystem
This callback can expect to receive a OpenAPI.Renderer.File.t/0
struct with formatted file
contents expressed as iodata
in the contents
field. It should write the file to the
filesystem at the appropriate location included in the location
field. While the return value
is irrelevant, a simple :ok
will suffice.
See OpenAPI.Renderer.Util.write/2
for the default implementation.
Link to this section Functions
@spec run(OpenAPI.State.t()) :: OpenAPI.State.t()