View Source OpenAPI.Processor behaviour (OpenAPI Generator v0.1.0-rc.4)

Phase two of code generation

The process phase begins with a decoded API description from the read phase. It may represent the contents of one or more files, including one or more root descriptions if supplemental files were used.

This library takes an "operation first" mindset when processing the description. Schemas are ignored until they are referenced by an operation (ex. as a response body). It is the job of this phase to observe all of the operations and their referenced schemas, process them into data structures more relevant to code generation, and prepare the data for rendering.

customization

Customization

At several points during code generation, it may be useful to customize the behaviour of the processor. For this purpose, this module is a Behaviour with most of its critical logic implemented as optional callbacks.

Link to this section Summary

Callbacks

Whether to render the given operation in the generated code

Whether to render the given schema in the generated code

Construct a docstring for the given operation

Choose the name of the client function for the given operation

Choose the names of the client function modules for the given operation

Collect a list of request content types and their associated schemas

Choose and cast the request method for the given operation

Collect a list of response status codes and their associated schemas

Choose the output format for the given schema

Choose the name of the module and type for the given schema

Functions

Run the processing phase of the code generator

Link to this section Callbacks

Link to this callback

ignore_operation?(state, operation_spec)

View Source (optional)
@callback ignore_operation?(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: boolean()

Whether to render the given operation in the generated code

If this function returns true, the operation will not appear in the generated code.

See OpenAPI.Processor.Ignore.ignore_operation?/2 for the default implementation.

Link to this callback

ignore_schema?(state, schema_spec)

View Source (optional)
@callback ignore_schema?(
  state :: OpenAPI.Processor.State.t(),
  schema_spec :: OpenAPI.Spec.Schema.t()
) ::
  boolean()

Whether to render the given schema in the generated code

If this function returns true, the schema will not appear in the generated code (unless it returns false when presented in another context) and a plain map will be used as its type.

See OpenAPI.Processor.Ignore.ignore_schema?/2 for the default implementation.

Link to this callback

operation_docstring(state, operation_spec, query_params)

View Source (optional)
@callback operation_docstring(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t(),
  query_params :: [OpenAPI.Processor.Operation.Param.t()]
) :: String.t()

Construct a docstring for the given operation

This function accepts the operation spec as well as a list of the processed query params associated with the operation.

See OpenAPI.Processor.Operation.docstring/3 for the default implementation.

Link to this callback

operation_function_name(state, operation_spec)

View Source (optional)
@callback operation_function_name(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: atom()

Choose the name of the client function for the given operation

This function accepts the operation spec and chooses a name for the client function that will be generated. The name must be unique within its module (see operation_module_names/2).

See OpenAPI.Processor.Naming.operation_function/2 for the default implementation.

Link to this callback

operation_module_names(state, operation_spec)

View Source (optional)
@callback operation_module_names(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: [module()]

Choose the names of the client function modules for the given operation

Each operation may have multiple client functions in different modules. This function accepts the operation spec and returns a list of all of its operation modules.

See OpenAPI.Processor.Naming.operation_modules/2 for the default implementation.

Link to this callback

operation_request_body(state, operation_spec)

View Source (optional)
@callback operation_request_body(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: OpenAPI.Processor.Operation.request_body_unprocessed()

Collect a list of request content types and their associated schemas

This function accepts the operation spec and returns a list of tuples containing the content type (ex. "application/json") and the schema associated with that type.

See OpenAPI.Processor.Operation.request_body/2 for the default implementation.

Link to this callback

operation_request_method(state, operation_spec)

View Source (optional)
@callback operation_request_method(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: OpenAPI.Processor.Operation.method()

Choose and cast the request method for the given operation

This function accepts the operation spec and must return the (lowercase) atom representing the HTTP method.

See OpenAPI.Processor.Operation.request_method/2 for the default implementation.

Link to this callback

operation_response_body(state, operation_spec)

View Source (optional)
@callback operation_response_body(
  state :: OpenAPI.Processor.State.t(),
  operation_spec :: OpenAPI.Spec.Path.Operation.t()
) :: OpenAPI.Processor.Operation.response_body_unprocessed()

Collect a list of response status codes and their associated schemas

This function accepts the operation spec and returns a list of tuples containing the status codes (ex. 200 or :default) and a list of tuples with the possible content types and the schema associated with that code and type.

See OpenAPI.Processor.Operation.response_body/2 for the default implementation.

Link to this callback

schema_format(state, schema)

View Source (optional)
@callback schema_format(
  state :: OpenAPI.Processor.State.t(),
  schema :: OpenAPI.Processor.Schema.t()
) ::
  OpenAPI.Processor.Format.format() | :unknown

Choose the output format for the given schema

Schemas can be output in a number of different ways, the most common of which are structs and typed maps. This callback chooses which output format to use for a processed schema. This decision may influence the naming (module and type) given to the schema.

The special value :unknown may be returned from this callback to delay / re-enqueue the schema for processing. This may appropriate, for example, if the schema's parent has not yet been processed. Note that continually returning :unknown can cause an infinite loop.

See OpenAPI.Processor.Format.schema_format/2 for the default implementation.

Link to this callback

schema_module_and_type(state, schema)

View Source (optional)
@callback schema_module_and_type(
  state :: OpenAPI.Processor.State.t(),
  schema :: OpenAPI.Processor.Schema.t()
) :: {module(), atom()}

Choose the name of the module and type for the given schema

Each module may contain multiple schemas with distinct types. By convention, the default type (used for single-schema modules) is :t, as in MySchema.t(). Additional schemas in the same module may represent variations on the default type, such as a User.public() schema containing a reduced set of fields from User.t().

See OpenAPI.Processor.Naming.schema_module_and_type/2 for the default implementation.

Link to this section Functions

@spec run(OpenAPI.State.t()) :: OpenAPI.State.t()

Run the processing phase of the code generator

This functions is used by the main OpenAPI module. It is unlikely that you will call this function directly, unless you are reimplementing one of the core functions. If this happens, please share your use-case with the maintainers; a plugin might be warranted.