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

Generation-time descriptor of a single Plug route built from an OpenAPI
operation.

Most fields drive the generated `pre_*.ex` / `*.ex` files and the umbrella
`router.ex` file. The `:source_meta` field is **public** and stable: it carries
the logical OpenAPI source identity for every schema fragment Oasis extracted
from the operation. Paths retain the user's OpenAPI URL spelling; parameter
names use Oasis's runtime identity (notably, header names are lowercase). It is
intended for tooling that consumes generation output and for the mix task's
own diagnostics.

Generated runtime modules deliberately do **not** embed `:source_meta`. Runtime
validation errors carry enough route/parameter context via `Plug.Conn` plus
`Oasis.BadRequestError` fields for callers to identify the failing input.

## `:source_meta` shape

    %{
      path_schema:   %{parameter_name => parameter_meta()},
      query_schema:  %{parameter_name => parameter_meta()},
      header_schema: %{parameter_name => parameter_meta()},
      cookie_schema: %{parameter_name => parameter_meta()},
      body_schema:   %{content_type   => body_meta()}
    }

where `parameter_meta()` is:

    %{
      path: String.t(),                # OpenAPI URL, e.g. "/users/{id}"
      http_verb: String.t(),           # "get" | "post" | ...
      parameter_location: String.t(),  # "path" | "query" | "header" | "cookie"
      parameter_name: String.t()
    }

OpenAPI parameters are uniquely identified by `(in, name)` within an
operation, which is already captured by `parameter_location` and
`parameter_name`. This is a logical operation/input identity: when an OpenAPI
Reference Object points to an external target, the metadata still identifies
the referencing operation and input and may not identify the exact raw target
object in the external document. No array index is exposed: it would be brittle
(sensitive to reordering) and would need to disambiguate path-item-level
vs operation-level parameters. Tooling that needs a JSON Pointer into the
raw document can build one from `path` + `http_verb` (and, if needed,
scan the operation's `parameters` array for a matching `(in, name)`). Header
names must be compared case-insensitively because `parameter_name` is the
lowercase runtime identity.

and `body_meta()` is:

    %{
      path: String.t(),
      http_verb: String.t(),
      content_type: String.t()
    }

# `generate_files_by_paths_spec`

---

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