Openapi

A lightweight OpenAPI-first routing, validation and documentation layer for Elixir/Phoenix applications.

It parses OpenAPI (YAML/JSON) definitions, generates Phoenix routes, optionally validates requests using JSON Schema, and provides built-in Swagger UI integration for interactive API documentation.

Usage

defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  import Openapi.Phoenix

  pipeline :api do
    plug :accepts, ["json"]
  end

  scope "/" do
    pipe_through :api

    openapi "priv/swagger.yaml"
    swagger_docs "/api-docs"
  end
end

The openapi macro is responsible for turning an OpenAPI definition into live Phoenix routes.

When used in a router, it performs the following steps at compile time:

• Reads the provided OpenAPI file (.yaml, .yml, or .json)
• Normalizes all paths to Phoenix format (e.g. /user/{id} → /user/:id)
• Generates Phoenix routes for every HTTP method defined under each path
• Attaches routing metadata for later dispatch

At runtime, requests are dispatched based on the generated metadata:

• If a global handler option is provided, it is used as the default module
• Otherwise, the macro uses the per-operation x-handler value from the OpenAPI file
• The operationId determines the function to call inside the handler module

Installation

If available in Hex, the package can be installed by adding openapi to your list of dependencies in mix.exs:

def deps do
  [
    {:openapi, "~> 0.1.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/openapi.

TODO:

• JSON schema validation
• Better definition merge (maybe conflict errors?)

License

MIT