Casted conn.params and conn.body_params do not match type spec. Dialyzer raises warnings.

[moxley]

The type spec for params and body_params is params() :: %{required(binary()) => param()} (https://hexdocs.pm/plug/1.7.2/Plug.Conn.html#t:params/0), but OpenApiSpex turns them into something like %{__struct__: module(), required(atom()) => term()}, or something else that doesn't match the spec. This causes dialyzer complaints in the controller actions for some situations.

IMO, OpenApiSpex shouldn't change conn.params or conn.body_params, as it breaks the contract with Plug. Instead, Spex can put the casted values in the :private attribute of the %Conn{}.

[mbuhot]

👍 It would be good to provide a custom Phoenix action plug that users can optionally mix in to controllers to get the cast params passed to the handler functions.

[hauleth]

@mbuhot this is what I am using in my project:

      def action(conn, _) do
        name = action_name(conn)

        if function_exported?(__MODULE__, name, 3) do
          apply(__MODULE__, name, [conn, conn.params, conn.body_params])
        else
          apply(__MODULE__, name, [conn, conn.params])
        end
      end

It could be changed to use :private or anything else in the first case.

[moxley]

It could be changed to use :private or anything else in the first case.

It would need to be done in Operation2

[mbuhot]

@moxley Shall we put a v4.0 milestone on this one? I can't come up with a non-breaking way to fix this.

[moxley]

@mbuhot: Yeah, I think it'll have to be in a major version.

[bforchhammer]

In case anyone else stumbles on this issue; this is how we solved it for ourselves:

defmodule Api.Spex do
  alias OpenApiSpex.{Info, OpenApi, Paths}
  @behaviour OpenApi

  @impl OpenApi
  def spec do
    %OpenApi{
      info: %Info{
        title: "My App",
        version: "1.0"
      },
      paths: Paths.from_router(Api.Router)
    }
    |> OpenApiSpex.resolve_schema_modules()
  end

  defmacro __using__(opts \\ []) do
    operations_module = Keyword.fetch!(opts, :operations_mod)

    quote do
      plug OpenApiSpex.Plug.CastAndValidate
      defdelegate open_api_operation(action), to: unquote(operations_module)

      # OpenApiSpex.Plug.CastAndValidate replaces the body_params with a struct based on the input schema; this breaks
      # dialyzer compatibility therefore we undo the change here and move the parsed and structified parameters into
      # conn.private.spex_params. We also supply them to the controller action as the 2nd argument which is a lot more
      # ergonomic than digging into the conn struct.
      # See https://github.com/open-api-spex/open_api_spex/issues/92
      plug :restore_body_params

      def restore_body_params(%Plug.Conn{body_params: %{__struct__: _} = body_params} = conn, _) do
        conn
        |> Plug.Conn.put_private(:spex_params, body_params)
        |> Map.put(:body_params, Map.from_struct(body_params))
      end

      def restore_body_params(conn, _), do: conn

      def action(conn, _) do
        name = action_name(conn)
        spex_params = conn.private[:spex_params]
        apply(__MODULE__, name, [conn, spex_params])
      end
    end
  end
end

This allows us to write controllers like this:

defmodule Api.UserController do
  use Api, :controller
  use Api.Spex, operations_mod: Api.Spex.UserOperations

  def create(%Plug.Conn{} = conn, %Api.Spex.UserCreateRequestSchema{username: username}) do
    # ...
    conn |> render(username: username)
  end
end

✨

[moxley]

Here is a temporary workaround for this problem:

defmodule MyAppWeb.MyController do
  use MyAppWeb, :controller
  use OpenApiSpex.Controller

  plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true

  # Use body params
  def create(conn, _params) do
    # Dialyzer misses the fact that body_params is being accessed
    body_params = Map.get(conn, :body_params)
    # The code is now free to reference compile-time atom keys from body params, without complaint from Dialyzer
    %{user: user_params} = body_params
  end

  # Use other params
  def create(conn, params) do
    # Dialyzer misses the fact that a param value is being accessed using an atom key
    id = Map.get(params, :id)
  end
end

[rsimmonsjr]

I dont think that last workaround will give the CastAndValidate functionality. The one from @bforchhammer might.

[moxley]

I dont think that last workaround will give the CastAndValidate functionality. The one from @bforchhammer might.

I'm not saying that it provides the CastAndValidate functionality. I'm saying is works around the issue described on this page.