Hi, I’m the author of phoenix_spectral | Hex which helps you keep openAPI specs, elixir types and conversion from json to internal data structures in sync. It and its sibling libraries are used at a set of production systems and the experience have been good so far. Happy to get feedback!

zoi | Hex is also worth looking into, but I’m not to familiar with that library.

Hello,

For all my new production work, I use oaskit (short for Open API Specification Kit), which I wrote.

On the client side, we use Orval, and to publish the APIs and link to other specifications for our apps and docs, we use Backstage (the UI is not great, but it works well).

If you want to look into oaskit, here is a simple example:

The spec module

Like with many other libraries, you start by defining a spec. Here, we’re pulling the routes from Phoenix controllers.

defmodule MyAppWeb.ApiSpec do
  use Oaskit
  alias Oaskit.Spec.Paths

  @impl true
  def spec do
    %{
      openapi: "3.1.1",
      info: %{title: "My App API", version: "1.0.0"},
      # Paths and schemas are collected from the operations declared in your
      # controllers, for every route matched by the filter.
      paths: Paths.from_router(MyAppWeb.Router, filter: &String.starts_with?(&1.path, "/api/"))
    }
  end
end

Router

In the router, besides your normal controller routes, you add the validation layer as a plug; otherwise, the OpenAPI doc is only declarative. With the plug, the library enforces validation of incoming requests.

You can also serve the OpenAPI spec itself, along with a UI page (Redoc) to explore it manually.

pipeline :api do
  plug :accepts, ["json"]
  plug Oaskit.Plugs.SpecProvider, spec: MyAppWeb.ApiSpec
end

scope "/api", MyAppWeb do
  pipe_through :api

  post "/users", UserController, :create

  # Serve the generated spec as JSON, plus a Redoc UI
  get "/openapi.json", Oaskit.SpecController, spec: MyAppWeb.ApiSpec
  get "/docs", Oaskit.SpecController, redoc: "/api/openapi.json"
end

Controller operations

In a controller, you can define schemas inline, though personally I’d group all schemas for a given domain in a single module.

# Oaskit docs help to wire validation to all controllers in the "web module"
use MyAppWeb, :controller
use JSV.Schema

# Request body
defschema CreateUser,
  name: string(minLength: 1),
  email: string(format: :email),
  age: optional(integer(minimum: 18, default: 18))

# Response body
defschema User,
  id: integer(),
  name: string(description: "The user's full name"),
  email: string()

operation :create,
  summary: "Create a user",
  # Schema modules are used here, but you can just use inline schemas like
  # %{type: :integer}
  request_body: CreateUser,
  # :created option here is for HTTP Error code 201, 200 would be [ok: User] or %{200 => User}
  responses: [created: User]

def create(conn, _params) do
  # With the validation layer, data is cast to a struct when using schema modules, but it's
  # totally optional. The raw data is always available.
  %CreateUser{name: name, email: email, age: age} = user_payload = body_params(conn)

  :ok = create_user(user_payload)

  user = %User{id: 1, name: name, email: email}

  conn
  |> put_status(:created)
  |> json(user)
end

Test

Testing was very important to me when designing the library. The tests use your OpenAPI definition module to know what to validate depending on the route or operation being called, so you know responses are correct with regard to what the spec declares. valid_response/3 asserts that the status, content type, and body all match the declared operation, and it returns the decoded body.

# To not state the spec module name in all tests, I generally define a wrapper like this in MyAppWeb.ConnCase
defp valid_response(conn, status) do
  Oaskit.Test.valid_response(MyAppWeb.ApiSpec, conn, status)
end

test "creates a user", %{conn: conn} do
  conn = post(conn, ~p"/api/users", %{name: "John", email: "john@example.com", age: 25})

  assert %{"id" => 1, "name" => "John"} = valid_response(conn, 201)
end

test "rejects invalid payloads", %{conn: conn} do
  # The ValidateRequest plug rejects this before the action runs
  conn = post(conn, ~p"/api/users", %{name: "", email: "nope"})

  assert json_response(conn, 422)
end

To publish to Backstage we just use the dump command from CI.

mix openapi.dump MyAppWeb.ApiSpec --pretty -o priv/openapi.json

There’s a Quickstart that walks through the full setup if you want to try it for real

If you want to migrate and you already have an OpenAPI spec document you can use it with oaskit, though in that case oaskit will just bring validation to the table, since your spec already exists on its own.

My understanding is that there are 2 main choices for Elixir + OpenAPI specs:

• Raw open_api_spex - Define specs manually. Flexible, but cumbersome

• Ash Framework + ash_json_api - Derive specs from your existing resources. Automagic, but requires you to use Ash Framework (may not be for everyone), and also requires you to conform to JSON:API style specs.