Deep merges two OpenAPI/Swagger definition maps.

Rules:

• paths are merged per path + method
• components are deeply merged
• tags are concatenated (deduped by name)
• servers are concatenated (deduped by url)
• everything else: right side overrides left

Normalizes an OpenAPI definition by merging it with default values.

This function ensures that the resulting OpenAPI document always contains the minimum required structure needed for downstream processing (such as route generation and Swagger UI rendering).

Converts an OpenAPI/Swagger paths definition into a list of Phoenix-compatible routes.

This function extracts HTTP operations from the OpenAPI document and transforms them into Openapi.Route structs that can later be used to generate Phoenix router entries or dispatch metadata.

Prefixes all OpenAPI path definitions with the given prefix.

This function transforms the "paths" section of an OpenAPI definition by adding a leading scope (e.g. /v1) to every defined route.

It preserves all HTTP operations and metadata under each path.

This function is primarily useful when integrating OpenAPI definitions inside Phoenix routers that use scope/2.

For example:

scope "/v1" do
  openapi "priv/swagger.yaml"
end

The OpenAPI file may define paths like:

/users
/users/{id}

But Phoenix will mount the routes under /v1, meaning the actual runtime routes become:

/v1/users
/v1/users/:id

In this case, you may want the OpenAPI document to reflect the same structure so that Swagger UI match the real routing layout.