View Source OpenAPI.Renderer behaviour (OpenAPI Generator v0.1.0-rc.3)

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

Link to this callback

format(state, file)

View Source (optional)
@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.

Link to this callback

location(state, file)

View Source (optional)
@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.

Link to this callback

render(state, file)

View Source (optional)
@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:

See OpenAPI.Renderer.Module.render/2 for the default implementation.

Link to this callback

render_default_client(state, file)

View Source (optional)
@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.

Link to this callback

render_moduledoc(state, file)

View Source (optional)
@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.

Link to this callback

render_operation(state, operation)

View Source (optional)
@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.

Link to this callback

render_operation_doc(state, operation)

View Source (optional)
@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.

Link to this callback

render_operation_function(state, operation)

View Source (optional)
@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.

Link to this callback

render_operation_spec(state, operation)

View Source (optional)
@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.

Link to this callback

render_operations(state, file)

View Source (optional)
@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.

Link to this callback

render_schema(state, file)

View Source (optional)
@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.

Link to this callback

render_schema_field_function(state, schemas)

View Source (optional)
@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.

Link to this callback

render_schema_struct(state, schemas)

View Source (optional)
@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.

Link to this callback

render_schema_types(state, schemas)

View Source (optional)
@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.

Link to this callback

render_using(state, file)

View Source (optional)
@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.

Link to this callback

write(state, file)

View Source (optional)
@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