Openapi.DispatchPlug (Openapi v0.1.0)

Copy Markdown View Source

Dispatch plug used by the OpenAPI router generated by Openapi.

This plug acts as the final execution layer for all OpenAPI-defined routes. Instead of using Phoenix controllers directly, routes are resolved at compile time and forwarded to a user-defined handler module and function derived from the OpenAPI operationId.

How it works

Each generated Phoenix route is attached with metadata:

private: %{
  openapi: %{
    server: :my_server,
    handler: MyApp.UsersAPI,
    operation_id: :get_user
  }
}

When a request matches a route, this plug:

  1. Extracts OpenAPI metadata from conn.private
  2. Resolves the handler module and operation function
  3. Invokes the handler using apply/3

OperationId normalization

OpenAPI operationId values are normalized before dispatch to match Elixir conventions:

operation_id: Macro.underscore(route.operation_id) |> String.to_atom()

Example:

"findPetsByStatus" -> :find_pets_by_status

This ensures compatibility with idiomatic Elixir function naming.

Expected handler format

Handlers are plain Elixir modules where each function corresponds to an OpenAPI operationId:

defmodule MyApp.UsersAPI do
  def get_user(conn, params) do
    Plug.Conn.send_resp(conn, 200, "ok")
  end
end

Dispatch rules

  • handler is either defined globally per file or per-route via x-handler
  • operation_id must match a function exported by the handler module
  • Functions are expected to have arity 2: (conn, params)