# `Mix.Oasis`
[🔗](https://github.com/xinz/oasis/blob/main/lib/mix/oasis.ex#L1)

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.

# `generation_file`

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

# `copy_from`

# `eval_from`

# `generator_paths`

# `module_alias`

# `name_space`

# `new`

```elixir
@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!`

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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*