OpenApiSpex is an Elixir lib to provide OpenAPI documentation for your Phoenix web application. The way it works is you annotate the controller functions with @doc statements where you specify what the request and responses should look like.

There is currently an issue with the lib where it relies on the documentation being available inside the compiled BEAM files at runtime which - if you use mix release - by default is not. This makes any requests to your entry points return a cryptic :chunk_not_found error. The reason is the documentation "chunk" inside your controller compiled file is not there (i.e. it was striped when mix release ran).

The workaround for this right now is to pass strip_beams: false in the mix release configuration in your iex.exs file:

  def project do
    [
      ...
      releases: releases()
    ]
  end

  defp releases() do
    [
      prod: [
        include_executables_for: [:unix],
        include_erts: true,
        strip_beams: false,
        quiet: false
      ]
    ]
  end

The only issue with this approach right now is that it will add a fair bit to your final package size (around 25MB extra in my 72MB project).

There is work in progress in the mix release process to allow more granular control over what gets stripped from the compiled files, which will allow us in the future to strip everything except, for instance, documentation (which is only 1 or 2MB).

Happy BEAMing