Expressive parameter validation riding on the shoulder of a giant
def deps do
[
{:parameters, "~> 2.0"}
]
end- Expressive and declarative but with the ability to extend via custom validation function
- Support to express Ecto's built-in validators
- Auto-generated documentation in the form of
@docand Open API Specification
Parameters behaves like the @doc attribute and basically annotates the function with information about the parameters.
At the moment there are 4 macros for defining parameters. These are backed by Ecto's field/3, embeds_one/3 and embeds_many/3.
You can nest however deep you want and Parameters will take care of defining the Ecto schemas
params do
optional :name, :string # => equivalent of `field :name, :string` and `cast`
requires :username, :string # => equivalent of `field :username, :string` and `validate_required`
optional :book, :map do # => equivalent of `embeds_one` and `cast_embed`
requires :isbn, :string
end
requires :books, :array do # => equivalent of `embeds_many` and `cast_embed(required: true)`
requires :isbn, :string
end
endOnce the schema is declared, you can use Parameters.params_for(conn | changeset) or Parameters.params_for(module_defined_in, function_defined_at, params) to validate any raw parameters.
{:ok, sanitized_params} | {:error, changeset} = Parameters.params_for(conn)Or if you'd like to extend the changeset with additional validations Parameters also exposes a function Parameters.changeset_for(conn) and Parameters.changeset_for(module_defined_in, function_defined_at, params) which allows you to do so like this:
{:ok, params} | {:error, changeset} =
conn
|> Parameters.changeset_for() # => %Ecto.Changeset{}
|> Changeset.validate_change(&custom_validator_fn/2) # => %Ecto.Changeset{}
|> Parameters.params_for(params) # => Validate and return sanitized paramsdefmodule MyApp.PostController do
use MyApp, :web
use Parameters
params do
# Schema fields + Changeset.validate_required
optional :limit, :integer, default: 10
optional :page, :integer, default: 1
requires :query, :string
# Schema embeds_many
requires :profiles, :array do
requires :access_key, :string
requires :secret_key, :string
end
# Schema embeds_one
requires :profile, :map do
requires :access_key, :string
requires :secret_key, :string
end
end
def index(conn, _params) do
with {:ok, params} <- Parameters.params_for(conn) do
json(conn, params)
else
{:error, %Ecto.Changeset{}} ->
# handle error
end
end
enddefmodule Parameters.Sanitizer do
use Plug.Builder
alias Ecto.Changeset
plug :sanitize
defp sanitize(conn, _opts) do
case Parameters.params_for(conn) do
{:ok, params} ->
Map.put(conn, :params, params)
{:error, changeset} ->
errors = errors_from_changeset(changeset)
conn
|> put_resp_content_type("application/json")
|> resp(:bad_request, Jason.encode!(errors))
|> send_resp()
|> halt()
end
end
defp errors_from_changeset(changeset) do
Changeset.traverse_errors(changeset, fn {msg, opts} ->
Enum.reduce(opts, msg, fn {key, value}, acc ->
String.replace(acc, "%{#{key}}", to_string(value))
end)
end)
end
end
defmodule MyApp.PostController do
use MyApp, :web
use Parameters
plug Parameters.Sanitizer
params do
# Schema fields + Changeset.validate_required
optional :limit, :integer, default: 10
optional :page, :integer, default: 1
requires :query, :string
# Schema embeds_many
requires :profiles, :array do
requires :access_key, :string
requires :secret_key, :string
end
# Schema embeds_one
requires :profile, :map do
requires :access_key, :string
requires :secret_key, :string
end
end
def index(conn, _params) do
# params are sanitized by plug
# errors are reported to user automatically
json(conn, params)
end
end
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent