Valspec.Controller (valspec v0.2.0)

A module to conveniently generate valspec definitions within Phoenix controllers.

## Example

defmodule MyAppWeb.ExampleUsersController do
  use MyAppWeb, :controller
  use Valspec.Controller

  valspec_create :create_user, summary: "Creates a User" do
    required(:first_name, :string, example: "Greg")
    required(:role, :enum, values: [:admin, :normal], default: :normal)
    optional(:last_name, :string, example: "Jones")
    optional(:age, :integer, minimum: 18)
  end

  def create(conn, params) do
        # `valspec_validate/2` - validates a map of parameters. Returns:
        #    - {:ok, map()} when params are valid
        #    - {:error, Ecto.%Changeset{}} when params are invalid
    with {:ok, user_params} <- valspec_validate(:create_user, params) do
      ...
    else
      {:error, %Ecto.Changeset{}} ->
        ...
    end
  end
end

Options:

tags- the Swagger tags for the module. Example: [tags: ["V3 Clients Api"]].
default_response_schema- defines a default response schema for use in Swagger docs
default_callback_schema- defines a default callback schema for use in Swagger docs (Callbacks)

Summary

Functions

valspec_create(name, opts, list)

Generates both a Goal validation struct and Swagger schema for a create controller action.

valspec_custom(action, opts)

Generates both a Goal validation struct and Swagger schema for a custom controller action.

valspec_custom(name, action, opts, list)

valspec_delete(opts)

Generates both a Goal validation struct and Swagger schema for a delete controller action.

valspec_index(opts)

Generates both a Goal validation struct and Swagger schema for an index controller action.

valspec_show(opts)

Generates both a Goal validation struct and Swagger schema for a show controller action.

valspec_update(name, opts, list)

Generates both a Goal validation struct and Swagger schema for an update controller action.

Functions

valspec_create(name, opts, list)

(macro)

@spec valspec_create(name :: String.t(), opts :: Keyword.t(), block :: any()) ::
  Macro.t()

Generates both a Goal validation struct and Swagger schema for a create controller action.

Example:

valspec_create :create_client,
summary: "Creates a client",
response_schema: MyAppWeb.Response do
  required(:name, :string, example: "Client 1")
  required(:type, :enum, values: [:vendor, :customer])
  required(:account_id, :uuid, example: "82b557d1-c529-4aff-b0fb-55df16add1b5")
end

Options:

summary- a summary of what the post request does.
response_schema- a response schema defined with the valspec_schema macro.
callback_schemas- a list of tuples with the name of a callback to a schema. Example: [{"Create User Webhook", MyApp.User.WebhookSchema}, {"Create Account Webhook", MyApp.User.WehookSchema}]

valspec_custom(action, opts)

(macro)

Generates both a Goal validation struct and Swagger schema for a custom controller action.

## Example 1:

  valspec_custom(:my_action, summary: "Hello world")

## Example 2:

  valspec_custom
    :my_validation_name
    :my_action,
    summary: "Hello world" do
        required(:id, :string)
        optional(:name, :string)
        optional(:location_id, :string,
            format: "uuid",
            example: "b388a4da-a3d6-42d4-8a98-4149f0007e6b",
            description: "the location_id of something..."
        )
  end

## Options:

summary - Swagger endpoint summary
response_schema - The schema module to generating the response schema

valspec_custom(name, action, opts, list)

(macro)

@spec valspec_custom(
  name :: atom(),
  action :: atom(),
  opts :: Keyword.t(),
  block :: any()
) :: Macro.t()

valspec_delete(opts)

(macro)

@spec valspec_delete(opts :: Keyword.t()) :: Macro.t()

Generates both a Goal validation struct and Swagger schema for a delete controller action.

## Example:

  valspec_delete(
    summary: "Deletes a client",
    response_schema: MyAppWeb.Response
  )

## Options:

summary - Swagger endpoint summary
response_schema - The schema module to generating the response schema
callback_schemas- a list of tuples with the name of a callback to a schema. Example: [{"Delete User Webhook", MyApp.User.WebhookSchema}, {"Delete Account Webhook", MyApp.User.WehookSchema}]

valspec_index(opts)

(macro)

@spec valspec_index(opts :: Keyword.t()) :: Macro.t()

Generates both a Goal validation struct and Swagger schema for an index controller action.

Example:

valspec_index(
  summary: "Lists all clients",
  response_schema:  MyAppWeb.IndexResponse,
)

Options:

summary- a summary of what the post request does.
response_schema- a response struct defined with the valspec_schema macro.

valspec_show(opts)

(macro)

Generates both a Goal validation struct and Swagger schema for a show controller action.

Example:

valspec_show(
  summary: "Show a single client",
  response_schema: MyAppApi.V3.Client.JSON.IndexResponse
)

Options:

summary- a summary of what the post request does.
response_schema- a response struct defined with the valspec_schema macro.

valspec_update(name, opts, list)

(macro)

@spec valspec_update(name :: String.t(), opts :: Keyword.t(), block :: any()) ::
  Macro.t()

Generates both a Goal validation struct and Swagger schema for an update controller action.

Example:

valspec_update :update_client,
  summary: "Updates a client",
  response_schema: MyAppWeb.Response do
  optional(:client_id, :uuid, example: "82b557d1-c529-4aff-b0fb-55df16add1b5")

  optional(:location_id, :string,
    format: "uuid",
    example: "b388a4da-a3d6-42d4-8a98-4149f0007e6b",
    description: "the location_id used to do stuff..."
  )
end

Options:

summary- a summary of what the post request does.
response_schema- a response schema defined with the valspec_schema macro.
callback_schemas- a list of tuples with the name of a callback to a schema. Example: [{"Update User Webhook", MyApp.User.WebhookSchema}, {"Update Account Webhook", MyApp.User.WehookSchema}]