defmodule ControllerHelpers do
  @moduledoc """
  Conveniences for building controllers.
  """
  use PhoenixSwagger

  @doc """
  Returns map of common swagger definitions.

  These definitions (data structures) are not specific to any controller or
  business domain logic.
  """
  def swagger_definitions_common do
    %{
      ErrorResource:
        swagger_schema do
          title("Error")

          description(
            "Error objects provide additional information about problems encountered while performing an operation."
          )

          properties do
            code(:string, "An application-specific error code, expressed as a string value.",
              required: true
            )

            detail(
              :string,
              "A human-readable explanation specific to this occurrence of the problem",
              required: true
            )

            id(:string, "A unique identifier for this particular occurrence of the problem",
              required: true
            )

            status(
              :string,
              "The HTTP status code applicable to this problem, expressed as a string value",
              required: true
            )

            title(:string, "Error title, usually HTTP reason phrase", required: true)

            source(
              Schema.new do
                properties do
                  parameter(
                    :string,
                    "A string indicating which URI query parameter caused the error",
                    default: nil,
                    required: false
                  )

                  pointer(
                    :string,
                    "A JSON Pointer [RFC6901] to the associated entity in the request document",
                    default: nil,
                    required: false
                  )
                end
              end
            )
          end
        end,
      Error: JsonApi.single(:ErrorResource)
    }
  end
end