Leverage Open Api 3.0 (Swagger) to document, test, validate and explore your Plug and Phoenix APIs.

• Generate and serve a JSON Open API (swagger) document from your code
• Use the spec to cast request params to well defined schema structs
• Validate params against schemas, eliminate bad requests before they hit your controllers
• Validate responses against schemas in tests, ensuring your docs are accurate and reliable
• Explore the API interactively with with SwaggerUI

Github: https://github.com/mbuhot/open_api_spex
Docs: https://hexdocs.pm/open_api_spex/
Hex: https://hex.pm/packages/open_api_spex

Integrating with phoenix controllers:

  @spec open_api_operation(atom) :: Operation.t
  def open_api_operation(action), do: apply(__MODULE__, :"#{action}_operation", [])

  @spec show_operation() :: Operation.t
  def show_operation() do
    %Operation{
      tags: ["users"],
      summary: "Show user",
      description: "Show a user by ID",
      operationId: "UserController.show",
      parameters: [
        Operation.parameter(:id, :path, :integer, "User ID", example: 123)
      ],
      responses: %{
        200 => Operation.response("User", "application/json", UserResponse)
      }
    }
  end
  def show(conn, %{"id" => id}) do
    {:ok, user} = MyApp.Users.find_by_id(id)
    json(conn, 200, user)
  end

Cast and validate params:

  plug OpenApiSpex.Plug.Cast
  plug OpenApiSpex.Plug.Validate

  def open_api_operation(action) do
    apply(__MODULE__, :"#{action}_operation", [])
  end

  def create_operation do
    import Operation
    %Operation{
      tags: ["users"],
      summary: "Create user",
      description: "Create a user",
      operationId: "UserController.create",
      parameters: [],
      requestBody: request_body("The user attributes", "application/json", UserRequest),
      responses: %{
        201 => response("User", "application/json", UserResponse)
      }
    }
  end

  def create(conn, request = %UserRequest{user: %User{name: name, email: email, birthday: birthday = %Date{}}}) do
    ...  
end