Mix.Oasis (oasis v0.7.0)

Copy Markdown View Source

Builds the generation plan consumed by Oasis Mix tasks.

new/2 prepares an Oasis.Spec.Document or decoded OpenAPI map and returns file descriptors. It does not write files itself. Tooling may inspect each descriptor's binding, including %Mix.Oasis.Router{source_meta: ...}, before passing the plan to its own writer.

Summary

Types

generation_file()

Functions

copy_from(apps, source_dir, mapping, opts \\ [])
eval_from(apps, source_file_path, binding)
generator_paths()
module_alias(name)
name_space(name_space)
new(spec, opts)

Prepares an OpenAPI document and returns generated-file descriptors.

prepare_json_schema!(schema, opts \\ [])

Prepares a JSON Schema entrypoint for generated code.

render_embedded_schemas(term)

Renders data containing already-compiled JSONSchex schemas into AST-friendly source. Raw maps remain ordinary data regardless of their key names.

Types

generation_file()

@type generation_file() :: {:eex | :new_eex, String.t(), String.t(), module(), term()}

Functions

copy_from(apps, source_dir, mapping, opts \\ [])

eval_from(apps, source_file_path, binding)

generator_paths()

module_alias(name)

name_space(name_space)

new(spec, opts)

@spec new(
  Oasis.Spec.Document.t() | map(),
  keyword()
) :: [generation_file()]

Prepares an OpenAPI document and returns generated-file descriptors.

Accepted inputs are a prepared Oasis.Spec.Document or a decoded OpenAPI map containing a Paths Object. Decoded maps are structurally resolved and normalized before generation.

Relevant options include :base_uri, :loader, :name_space, and :router. Callers passing Oasis's legacy pre-grouped parameter maps must opt in with normalized_parameters: true; decoded OpenAPI Parameter Objects use arrays and are validated strictly by default.

Each returned tuple contains the write policy, target path, template path, target module, and template binding. The Mix task consumes the same plan.

prepare_json_schema!(schema, opts \\ [])

Prepares a JSON Schema entrypoint for generated code.

When :root_spec and :entry are available, JSONSchex bundles the fragment in its containing OpenAPI document context and returns a standalone schema. Otherwise, the schema is treated as already standalone.

Options

  • :root_spec — the containing OpenAPI document map. Required together with :entry for fragment bundling. Without it, the schema is assumed to be self-contained.
  • :entry — JSON Pointer or URI reference identifying the schema fragment to bundle (e.g. "#/paths/~1users/post/requestBody/content/application~1json/schema"). Forwarded to JSONSchex.bundle_fragment/2.
  • :base_uri — base URI used to resolve relative external refs inside :root_spec. Forwarded to JSONSchex.bundle_fragment/2.
  • :loader — external-resource loader. Defaults to &Oasis.Spec.Document.load_external/1. Pass loader: nil to opt out of external loading (any unresolved external $ref then raises).

Behavior

Returns the bundled (or pass-through) JSON Schema map/boolean as data — not a compiled %JSONSchex.Types.Schema{}. The returned map is suitable for embedding into generated pre_*.ex modules via JSONSchex.Schema.compile!/2 at compile time.

Raises ArgumentError if bundling or the compile precheck fails. Error messages include the entry and base URI for diagnostics.

render_embedded_schemas(term)

Renders data containing already-compiled JSONSchex schemas into AST-friendly source. Raw maps remain ordinary data regardless of their key names.