No OneTemporary
Actions

Size

44 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/README.md b/README.md
	index 51995a9..9646a2d 100644
	--- a/README.md
	+++ b/README.md
	@@ -1,296 +1,299 @@
	# Open API Spex
	[![Build Status](https://travis-ci.org/mbuhot/open_api_spex.svg?branch=master)](https://travis-ci.org/mbuhot/open_api_spex)
	[![Hex.pm](https://img.shields.io/hexpm/v/open_api_spex.svg)](https://hex.pm/packages/open_api_spex)


	Leverage Open Api Specification 3 (swagger) to document, test, validate and explore your Plug and Phoenix APIs.

	- Generate and serve a JSON Open Api Spec 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](https://swagger.io/swagger-ui/)

	Full documentation available on [hexdocs](https://hexdocs.pm/open_api_spex/)

	## Installation

	The package can be installed by adding `open_api_spex` to your list of dependencies in `mix.exs`:

	```elixir
	def deps do
	[
	{:open_api_spex, "~> 2.3"}
	]
	end
	```

	## Generate Spec

	Start by adding an `ApiSpec` module to your application to populate an `OpenApiSpex.OpenApi` struct.

	```elixir
	defmodule MyApp.ApiSpec do
	alias OpenApiSpex.{OpenApi, Server, Info, Paths}

	def spec do
	%OpenApi{
	servers: [
	# Populate the Server info from a phoenix endpoint
	Server.from_endpoint(MyAppWeb.Endpoint, otp_app: :my_app)
	],
	info: %Info{
	title: "My App",
	version: "1.0"
	},
	# populate the paths from a phoenix router
	paths: Paths.from_router(MyAppWeb.Router)
	}
	\|> OpenApiSpex.resolve_schema_modules() # discover request/response schemas from path specs
	end
	end
	```

	For each plug (controller) that will handle api requests, add an `open_api_operation` callback.
	It will be passed the plug opts that were declared in the router, this will be the action for a phoenix controller. The callback populates an `OpenApiSpex.Operation` struct describing the plug/action.

	```elixir
	defmodule MyApp.UserController do
	alias OpenApiSpex.Operation
	alias MyApp.Schemas.UserResponse

	@spec open_api_operation(any) :: 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
	end
	```

	Declare the JSON schemas for request/response bodies in a `Schemas` module:
	Each module should implement the `OpenApiSpex.Schema` behaviour.
	The only callback is `schema/0`, which should return an `OpenApiSpex.Schema` struct.
	You may optionally declare a struct, linked to the JSON schema through the `x-struct` extension property.
	See `OpenApiSpex.schema/1` macro for a convenient way to reduce some boilerplate.

	```elixir
	defmodule MyApp.Schemas do
	alias OpenApiSpex.Schema

	defmodule User do
	@behaviour OpenApiSpex.Schema
	@derive [Poison.Encoder]
	@schema %Schema{
	title: "User",
	description: "A user of the app",
	type: :object,
	properties: %{
	id: %Schema{type: :integer, description: "User ID"},
	name: %Schema{type: :string, description: "User name"},
	email: %Schema{type: :string, description: "Email address", format: :email},
	inserted_at: %Schema{type: :string, description: "Creation timestamp", format: :datetime},
	updated_at: %Schema{type: :string, description: "Update timestamp", format: :datetime}
	},
	required: [:name, :email],
	example: %{
	"id" => 123,
	"name" => "Joe",
	"email" => "joe@gmail.com"
	}
	"x-struct": __MODULE__
	}
	def schema, do: @schema
	defstruct Map.keys(@schema.properties)
	end

	defmodule UserResponse do
	require OpenApiSpex

	# OpenApiSpex.schema/1 macro can be optionally used to reduce boilerplate code
	OpenApiSpex.schema %{
	title: "UserResponse",
	description: "Response schema for single user",
	type: :object,
	properties: %{
	data: User
	}
	}
	end
	end
	```

	Now you can create a mix task to write the swagger file to disk:

	```elixir
	defmodule Mix.Tasks.MyApp.OpenApiSpec do
	def run([output_file]) do
	json =
	MyApp.ApiSpec.spec()
	\|> Poison.encode!(pretty: true)

	:ok = File.write!(output_file, json)
	end
	end
	```

	Generate the file with: `mix myapp.openapispec spec.json`

	## Serve Spec

	To serve the API spec from your application, first add the `OpenApiSpex.Plug.PutApiSpec` plug somewhere in the pipeline.

	```elixir
	pipeline :api do
	plug OpenApiSpex.Plug.PutApiSpec, module: MyApp.ApiSpec
	end
	```

	Now the spec will be available for use in downstream plugs.
	The `OpenApiSpex.Plug.RenderSpec` plug will render the spec as JSON:

	```elixir
	scope "/api" do
	pipe_through :api
	resources "/users", MyApp.UserController, only: [:create, :index, :show]
	get "/openapi", OpenApiSpex.Plug.RenderSpec, []
	end
	```

	## Serve Swagger UI

	Once your API spec is available through a route, the `OpenApiSpex.Plug.SwaggerUI` plug can be used to serve a SwaggerUI interface. The `path:` plug option must be supplied to give the path to the API spec.

	All javascript and CSS assets are sourced from cdnjs.cloudflare.com, rather than vendoring into this package.

	```elixir
	scope "/" do
	pipe_through :browser # Use the default browser stack

	get "/", MyAppWeb.PageController, :index
	get "/swaggerui", OpenApiSpex.Plug.SwaggerUI, path: "/api/openapi"
	end

	scope "/api" do
	pipe_through :api

	resources "/users", MyAppWeb.UserController, only: [:create, :index, :show]
	get "/openapi", OpenApiSpex.Plug.RenderSpec, []
	end
	```

	## Cast Params

	-Add the `OpenApiSpex.Plug.Cast` plug to a controller to cast the request parameters to elixir types defined by the operation schema.
	+Add the `OpenApiSpex.Plug.Cast` plug to a controller to cast the request parameters and body to elixir types defined by the operation schema.

	```elixir
	plug OpenApiSpex.Plug.Cast, operation_id: "UserController.show"
	```

	The `operation_id` can be inferred when used from a Phoenix controller from the contents of `conn.private`.

	```elixir
	defmodule MyApp.UserController do
	use MyAppWeb, :controller
	alias OpenApiSpex.Operation
	alias MyApp.Schemas.{User, UserRequest, UserResponse}

	plug OpenApiSpex.Plug.Cast

	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: [],
	+ parameters: [
	+ parameter(:id, :query, :integer, "user ID")
	+ ],
	requestBody: request_body("The user attributes", "application/json", UserRequest),
	responses: %{
	201 => response("User", "application/json", UserResponse)
	}
	}
	end

	- def create(conn, %UserRequest{user: %User{name: name, email: email, birthday: birthday = %Date{}}}) do
	- # params are cast to UserRequest struct
	+ def create(conn = %{body_params: %UserRequest{user: %User{name: name, email: email, birthday: birthday = %Date{}}}}, %{id: id}) do
	+ # conn.body_params cast to UserRequest struct
	+ # conn.params.id cast to integer
	end
	end
	```
	See also `OpenApiSpex.cast/3` and `OpenApiSpex.Schema.cast/3` for more examples outside of a `plug` pipeline.


	## Validate Params

	Add both the `OpenApiSpex.Plug.Cast` and `OpenApiSpex.Plug.Validate` plugs to your controller / plug:

	```elixir
	plug OpenApiSpex.Plug.Cast
	plug OpenApiSpex.Plug.Validate
	```

	Now the client will receive a 422 response whenever the request fails to meet the validation rules from the api spec.

	The response body will include the validation error message:

	```
	#/user/name: Value does not match pattern: [a-zA-Z][a-zA-Z0-9_]+
	```

	See `OpenApiSpex.validate/3` and `OpenApiSpex.Schema.validate/3` for usage outside of a plug pipeline.

	## Validate Examples

	As schemas evolve, you may want to confirm that the examples given match the schemas.
	Use the `OpenApiSpex.Test.Assertions` module to assert on schema validations.

	```elixir
	Use ExUnit.Case
	import OpenApiSpex.Test.Assertions

	test "UsersResponse example matches schema" do
	api_spec = MyApp.ApiSpec.spec()
	schema = MyApp.Schemas.UsersResponse.schema()
	assert_schema(schema.example, "UsersResponse", api_spec)
	end
	```

	## Validate Responses

	Api responses can be tested against schemas using `OpenApiSpex.Test.Assertions` also:

	```elixir
	use MyApp.ConnCase
	import OpenApiSpex.Test.Assertions

	test "UserController produces a UsersResponse", %{conn: conn} do
	api_spec = MyApp.ApiSpec.spec()
	json =
	conn
	\|> get(user_path(conn, :index))
	\|> json_response(200)

	assert_schema(json, "UsersResponse", api_spec)
	end
	```
	diff --git a/lib/open_api_spex.ex b/lib/open_api_spex.ex
	index f459e91..3fa9c2e 100644
	--- a/lib/open_api_spex.ex
	+++ b/lib/open_api_spex.ex
	@@ -1,123 +1,126 @@
	defmodule OpenApiSpex do
	@moduledoc """
	Provides the entry-points for defining schemas, validating and casting.
	"""

	alias OpenApiSpex.{OpenApi, Operation, Reference, Schema, SchemaResolver}

	@doc """
	Adds schemas to the api spec from the modules specified in the Operations.

	Eg, if the response schema for an operation is defined with:

	responses: %{
	200 => Operation.response("User", "application/json", UserResponse)
	}

	Then the `UserResponse.schema()` function will be called to load the schema, and
	a `Reference` to the loaded schema will be used in the operation response.

	See `OpenApiSpex.schema` macro for a convenient syntax for defining schema modules.
	"""
	@spec resolve_schema_modules(OpenApi.t) :: OpenApi.t
	def resolve_schema_modules(spec = %OpenApi{}) do
	SchemaResolver.resolve_schema_modules(spec)
	end

	@doc """
	Cast params to conform to a `OpenApiSpex.Schema`.

	See `OpenApiSpex.Schema.cast/3` for additional examples and details.
	"""
	@spec cast(OpenApi.t, Schema.t \| Reference.t, any) :: {:ok, any} \| {:error, String.t}
	def cast(spec = %OpenApi{}, schema = %Schema{}, params) do
	Schema.cast(schema, params, spec.components.schemas)
	end
	def cast(spec = %OpenApi{}, schema = %Reference{}, params) do
	Schema.cast(schema, params, spec.components.schemas)
	end

	@doc """
	Cast all params in `Plug.Conn` to conform to the schemas for `OpenApiSpex.Operation`.

	+ Returns `{:ok, Plug.Conn.t}` with `params` and `body_params` fields updated if successful,
	+ or `{:error, reason}` if casting fails.
	+
	`content_type` may optionally be supplied to select the `requestBody` schema.
	"""
	- @spec cast(OpenApi.t, Operation.t, Plug.Conn.t, content_type \| nil) :: {:ok, any} \| {:error, String.t}
	+ @spec cast(OpenApi.t, Operation.t, Plug.Conn.t, content_type \| nil) :: {:ok, Plug.Conn.t} \| {:error, String.t}
	when content_type: String.t
	def cast(spec = %OpenApi{}, operation = %Operation{}, conn = %Plug.Conn{}, content_type \\ nil) do
	Operation.cast(operation, conn, content_type, spec.components.schemas)
	end

	@doc """
	Validate params against `OpenApiSpex.Schema`.

	See `OpenApiSpex.Schema.validate/3` for examples of error messages.
	"""
	@spec validate(OpenApi.t, Schema.t \| Reference.t, any) :: :ok \| {:error, String.t}
	def validate(spec = %OpenApi{}, schema = %Schema{}, params) do
	Schema.validate(schema, params, spec.components.schemas)
	end
	def validate(spec = %OpenApi{}, schema = %Reference{}, params) do
	Schema.validate(schema, params, spec.components.schemas)
	end

	@doc """
	Validate all params in `Plug.Conn` against `OpenApiSpex.Operation` `parameter` and `requestBody` schemas.

	`content_type` may be optionally supplied to select the `requestBody` schema.
	"""
	@spec validate(OpenApi.t, Operation.t, Plug.Conn.t, content_type \| nil) :: :ok \| {:error, String.t}
	when content_type: String.t
	def validate(spec = %OpenApi{}, operation = %Operation{}, conn = %Plug.Conn{}, content_type \\ nil) do
	Operation.validate(operation, conn, content_type, spec.components.schemas)
	end

	@doc """
	Declares a struct based `OpenApiSpex.Schema`

	- defines the schema/0 callback
	- ensures the schema is linked to the module by "x-struct" extension property
	- defines a struct with keys matching the schema properties
	- defines a @type `t` for the struct
	- derives a `Poison.Encoder` for the struct

	See `OpenApiSpex.Schema` for additional examples and details.

	## Example

	require OpenApiSpex

	defmodule User do
	OpenApiSpex.schema %{
	title: "User",
	description: "A user of the app",
	type: :object,
	properties: %{
	id: %Schema{type: :integer, description: "User ID"},
	name: %Schema{type: :string, description: "User name", pattern: ~r/[a-zA-Z][a-zA-Z0-9_]+/},
	email: %Schema{type: :string, description: "Email address", format: :email},
	inserted_at: %Schema{type: :string, description: "Creation timestamp", format: :'date-time'},
	updated_at: %Schema{type: :string, description: "Update timestamp", format: :'date-time'}
	},
	required: [:name, :email],
	example: %{
	"id" => 123,
	"name" => "Joe User",
	"email" => "joe@gmail.com",
	"inserted_at" => "2017-09-12T12:34:55Z",
	"updated_at" => "2017-09-13T10:11:12Z"
	}
	}
	end
	"""
	defmacro schema(body) do
	quote do
	@behaviour OpenApiSpex.Schema
	@schema struct(OpenApiSpex.Schema, Map.put(unquote(body), :"x-struct", __MODULE__))
	def schema, do: @schema
	@derive [Poison.Encoder]
	defstruct Schema.properties(@schema)
	@type t :: %__MODULE__{}
	end
	end
	end
	diff --git a/lib/open_api_spex/operation.ex b/lib/open_api_spex/operation.ex
	index e90c4bd..6624458 100644
	--- a/lib/open_api_spex/operation.ex
	+++ b/lib/open_api_spex/operation.ex
	@@ -1,222 +1,221 @@
	defmodule OpenApiSpex.Operation do
	@moduledoc """
	Defines the `OpenApiSpex.Operation.t` type.
	"""
	alias OpenApiSpex.{
	Callback,
	ExternalDocumentation,
	MediaType,
	Operation,
	Parameter,
	Reference,
	RequestBody,
	Response,
	Responses,
	Schema,
	SecurityRequirement,
	Server,
	}

	@enforce_keys :responses
	defstruct [
	:tags,
	:summary,
	:description,
	:externalDocs,
	:operationId,
	:parameters,
	:requestBody,
	:responses,
	:callbacks,
	:deprecated,
	:security,
	:servers
	]

	@typedoc """
	[Operation Object](https://swagger.io/specification/#operationObject)

	Describes a single API operation on a path.
	"""
	@type t :: %__MODULE__{
	tags: [String.t] \| nil,
	summary: String.t \| nil,
	description: String.t \| nil,
	externalDocs: ExternalDocumentation.t \| nil,
	operationId: String.t \| nil,
	parameters: [Parameter.t \| Reference.t] \| nil,
	requestBody: RequestBody.t \| Reference.t \| nil,
	responses: Responses.t,
	callbacks: %{String.t => Callback.t \| Reference.t} \| nil,
	deprecated: boolean \| nil,
	security: [SecurityRequirement.t] \| nil,
	servers: [Server.t] \| nil
	}

	@doc """
	Constructs an Operation struct from the plug and opts specified in the given route
	"""
	@spec from_route(PathItem.route) :: t
	def from_route(route) do
	from_plug(route.plug, route.opts)
	end

	@doc """
	Constructs an Operation struct from plug module and opts
	"""
	@spec from_plug(module, any) :: t
	def from_plug(plug, opts) do
	plug.open_api_operation(opts)
	end

	@doc """
	Shorthand for constructing a Parameter name, location, type, description and optional examples
	"""
	@spec parameter(atom, Parameter.location, Reference.t \| Schema.t \| atom, String.t, keyword) :: Parameter.t
	def parameter(name, location, type, description, opts \\ []) do
	params =
	[name: name, in: location, description: description, required: location == :path]
	\|> Keyword.merge(opts)

	Parameter
	\|> struct(params)
	\|> Parameter.put_schema(type)
	end

	@doc """
	Shorthand for constructing a RequestBody with description, media_type, schema and optional examples
	"""
	@spec request_body(String.t, String.t, (Schema.t \| Reference.t \| module), keyword) :: RequestBody.t
	def request_body(description, media_type, schema_ref, opts \\ []) do
	%RequestBody{
	description: description,
	content: %{
	media_type => %MediaType{
	schema: schema_ref,
	example: opts[:example],
	examples: opts[:examples]
	}
	},
	required: opts[:required] \|\| false
	}
	end

	@doc """
	Shorthand for constructing a Response with description, media_type, schema and optional examples
	"""
	@spec response(String.t, String.t, (Schema.t \| Reference.t \| module), keyword) :: Response.t
	def response(description, media_type, schema_ref, opts \\ []) do
	%Response{
	description: description,
	content: %{
	media_type => %MediaType {
	schema: schema_ref,
	example: opts[:example],
	examples: opts[:examples]
	}
	}
	}
	end

	@doc """
	Cast params to the types defined by the schemas of the operation parameters and requestBody
	"""
	- @spec cast(Operation.t, Conn.t, String.t \| nil, %{String.t => Schema.t}) :: {:ok, map} \| {:error, String.t}
	+ @spec cast(Operation.t, Conn.t, String.t \| nil, %{String.t => Schema.t}) :: {:ok, Plug.Conn.t} \| {:error, String.t}
	def cast(operation = %Operation{}, conn = %Plug.Conn{}, content_type, schemas) do
	parameters = Enum.filter(operation.parameters \|\| [], fn p -> Map.has_key?(conn.params, Atom.to_string(p.name)) end)
	with :ok <- check_query_params_defined(conn, operation.parameters),
	{:ok, parameter_values} <- cast_parameters(parameters, conn.params, schemas),
	- {:ok, body} <- cast_request_body(operation.requestBody, conn.params, content_type, schemas) do
	- {:ok, Map.merge(parameter_values, body)}
	+ {:ok, body} <- cast_request_body(operation.requestBody, conn.body_params, content_type, schemas) do
	+ {:ok, %{conn \| params: parameter_values, body_params: body}}
	end
	end

	@spec check_query_params_defined(Conn.t, list \| nil) :: :ok \| {:error, String.t}
	defp check_query_params_defined(%Plug.Conn{} = conn, defined_params) when is_nil(defined_params) do
	case conn.query_params do
	%{} -> :ok
	_ -> {:error, "No query parameters defined for this operation"}
	end
	end
	defp check_query_params_defined(%Plug.Conn{} = conn, defined_params) when is_list(defined_params) do
	defined_query_params = for param <- defined_params, param.in == :query, into: MapSet.new(), do: to_string(param.name)
	case validate_parameter_keys(Map.keys(conn.query_params), defined_query_params) do
	{:error, param} -> {:error, "Undefined query parameter: #{inspect(param)}"}
	:ok -> :ok
	end
	end

	@spec validate_parameter_keys([String.t], MapSet.t) :: {:error, String.t} \| :ok
	defp validate_parameter_keys([], _defined_params), do: :ok
	defp validate_parameter_keys([param\|params], defined_params) do
	case MapSet.member?(defined_params, param) do
	false -> {:error, param}
	_ -> validate_parameter_keys(params, defined_params)
	end
	end

	@spec cast_parameters([Parameter.t], map, %{String.t => Schema.t}) :: {:ok, map} \| {:error, String.t}
	defp cast_parameters([], _params, _schemas), do: {:ok, %{}}
	defp cast_parameters([p \| rest], params = %{}, schemas) do
	with {:ok, cast_val} <- Schema.cast(Parameter.schema(p), params[Atom.to_string(p.name)], schemas),
	{:ok, cast_tail} <- cast_parameters(rest, params, schemas) do
	{:ok, Map.put_new(cast_tail, p.name, cast_val)}
	end
	end

	@spec cast_request_body(RequestBody.t \| nil, map, String.t \| nil, %{String.t => Schema.t}) :: {:ok, map} \| {:error, String.t}
	defp cast_request_body(nil, _, _, _), do: {:ok, %{}}
	defp cast_request_body(%RequestBody{content: content}, params, content_type, schemas) do
	schema = content[content_type].schema
	Schema.cast(schema, params, schemas)
	end

	@doc """
	Validate params against the schemas of the operation parameters and requestBody
	"""
	@spec validate(Operation.t, Conn.t, String.t \| nil, %{String.t => Schema.t}) :: :ok \| {:error, String.t}
	def validate(operation = %Operation{}, conn = %Plug.Conn{}, content_type, schemas) do
	with :ok <- validate_required_parameters(operation.parameters \|\| [], conn.params),
	parameters <- Enum.filter(operation.parameters \|\| [], &Map.has_key?(conn.params, &1.name)),
	- {:ok, remaining} <- validate_parameter_schemas(parameters, conn.params, schemas),
	- :ok <- validate_body_schema(operation.requestBody, remaining, content_type, schemas) do
	+ :ok <- validate_parameter_schemas(parameters, conn.params, schemas),
	+ :ok <- validate_body_schema(operation.requestBody, conn.body_params, content_type, schemas) do
	:ok
	end
	end

	@spec validate_required_parameters([Parameter.t], map) :: :ok \| {:error, String.t}
	defp validate_required_parameters(parameter_list, params = %{}) do
	required =
	parameter_list
	\|> Stream.filter(fn parameter -> parameter.required end)
	\|> Enum.map(fn parameter -> parameter.name end)

	missing = required -- Map.keys(params)
	case missing do
	[] -> :ok
	_ -> {:error, "Missing required parameters: #{inspect(missing)}"}
	end
	end

	- @spec validate_parameter_schemas([Parameter.t], map, %{String.t => Schema.t}) :: {:ok, map} \| {:error, String.t}
	- defp validate_parameter_schemas([], %{} = params, _schemas), do: {:ok, params}
	+ @spec validate_parameter_schemas([Parameter.t], map, %{String.t => Schema.t}) :: :ok \| {:error, String.t}
	+ defp validate_parameter_schemas([], %{} = params, _schemas), do: :ok
	defp validate_parameter_schemas([p \| rest], %{} = params, schemas) do
	{:ok, parameter_value} = Map.fetch(params, p.name)
	- with :ok <- Schema.validate(Parameter.schema(p), parameter_value, schemas),
	- {:ok, remaining} <- validate_parameter_schemas(rest, params, schemas) do
	- {:ok, Map.delete(remaining, p.name)}
	+ with :ok <- Schema.validate(Parameter.schema(p), parameter_value, schemas) do
	+ validate_parameter_schemas(rest, params, schemas)
	end
	end

	@spec validate_body_schema(RequestBody.t \| nil, map, String.t \| nil, %{String.t => Schema.t}) :: :ok \| {:error, String.t}
	defp validate_body_schema(nil, _, _, _), do: :ok
	defp validate_body_schema(%RequestBody{required: false}, params, _content_type, _schemas) when map_size(params) == 0 do
	:ok
	end
	defp validate_body_schema(%RequestBody{content: content}, params, content_type, schemas) do
	content
	\|> Map.get(content_type)
	\|> Map.get(:schema)
	\|> Schema.validate(params, schemas)
	end
	end
	diff --git a/lib/open_api_spex/plug/cast.ex b/lib/open_api_spex/plug/cast.ex
	index f58728c..6b06d13 100644
	--- a/lib/open_api_spex/plug/cast.ex
	+++ b/lib/open_api_spex/plug/cast.ex
	@@ -1,86 +1,88 @@
	defmodule OpenApiSpex.Plug.Cast do
	@moduledoc """
	- Module plug that will cast the `Conn.params` according to the schemas defined for the operation.
	+ Module plug that will cast the `Conn.params` and `Conn.body_params` according to the schemas defined for the operation.
	+ Note that when using this plug, the body params are no longer merged into `Conn.params` and must be read from `Conn.body_params`
	+ separately.

	The operation_id can be given at compile time as an argument to `init`:

	plug OpenApiSpex.Plug.Cast, operation_id: "MyApp.ShowUser"

	For phoenix applications, the operation_id can be obtained at runtime automatically.

	defmodule MyAppWeb.UserController do
	use Phoenix.Controller
	plug OpenApiSpex.Plug.Cast
	...
	end

	If you want customize the error response, you can provide the `:render_error` option to register a plug which creates
	a custom response in the case of a validation error.

	## Example

	defmodule MyAppWeb.UserController do
	use Phoenix.Controller
	plug OpenApiSpex.Plug.Cast,
	render_error: MyApp.RenderError

	...
	end

	defmodule MyApp.RenderError do
	def init(opts), do: opts

	def call(conn, reason) do
	msg = %{error: reason} \|> Posion.encode!()

	conn
	\|> Conn.put_resp_content_type("application/json")
	\|> Conn.send_resp(400, msg)
	end
	end
	"""

	@behaviour Plug

	alias Plug.Conn

	@impl Plug
	def init(opts), do: Keyword.put_new(opts, :render_error, OpenApiSpex.Plug.DefaultRenderError)

	@impl Plug
	def call(conn = %{private: %{open_api_spex: private_data}}, operation_id: operation_id, render_error: render_error) do
	spec = private_data.spec
	operation = private_data.operation_lookup[operation_id]
	content_type = Conn.get_req_header(conn, "content-type")
	\|> Enum.at(0)
	\|> String.split(";")
	\|> Enum.at(0)
	private_data = Map.put(private_data, :operation_id, operation_id)
	conn = Conn.put_private(conn, :open_api_spex, private_data)

	case OpenApiSpex.cast(spec, operation, conn, content_type) do
	- {:ok, params} -> %{conn \| params: params}
	+ {:ok, conn} -> conn
	{:error, reason} ->
	opts = render_error.init(reason)

	conn
	\|> render_error.call(opts)
	\|> Plug.Conn.halt()
	end
	end
	def call(conn = %{private: %{phoenix_controller: controller, phoenix_action: action, open_api_spex: _pd}}, opts) do
	operation_id = controller.open_api_operation(action).operationId
	if (operation_id) do
	call(conn, Keyword.put(opts, :operation_id, operation_id))
	else
	raise "operationId was not found in action API spec"
	end
	end
	def call(_conn = %{private: %{open_api_spex: _pd}}, _opts) do
	raise ":operation_id was neither provided nor inferred from conn. Consider putting plug OpenApiSpex.Plug.Cast rather into your phoenix controller."
	end
	def call(_conn, _opts) do
	raise ":open_api_spex was not found under :private. Maybe OpenApiSpex.Plug.PutApiSpec was not called before?"
	end

	end
	diff --git a/test/open_api_spex_test.exs b/test/open_api_spex_test.exs
	index 4607510..0ccdb0f 100644
	--- a/test/open_api_spex_test.exs
	+++ b/test/open_api_spex_test.exs
	@@ -1,67 +1,67 @@
	defmodule OpenApiSpexTest do
	use ExUnit.Case
	alias OpenApiSpexTest.ApiSpec

	describe "OpenApi" do
	test "compete" do
	spec = ApiSpec.spec()
	assert spec
	end

	test "Valid Request" do
	request_body = %{
	"user" => %{
	"id" => 123,
	"name" => "asdf",
	"email" => "foo@bar.com",
	"updated_at" => "2017-09-12T14:44:55Z"
	}
	}

	conn =
	:post
	\|> Plug.Test.conn("/api/users", Poison.encode!(request_body))
	\|> Plug.Conn.put_req_header("content-type", "application/json; charset=UTF-8")
	\|> OpenApiSpexTest.Router.call([])

	- assert conn.params == %OpenApiSpexTest.Schemas.UserRequest{
	+ assert conn.body_params == %OpenApiSpexTest.Schemas.UserRequest{
	user: %OpenApiSpexTest.Schemas.User{
	id: 123,
	name: "asdf",
	email: "foo@bar.com",
	updated_at: ~N[2017-09-12T14:44:55Z] \|> DateTime.from_naive!("Etc/UTC")
	}
	}

	assert Poison.decode!(conn.resp_body) == %{
	"data" => %{
	"email" => "foo@bar.com",
	"id" => 1234,
	"inserted_at" => nil,
	"name" => "asdf",
	"updated_at" => "2017-09-12T14:44:55Z"
	}
	}
	end

	test "Invalid Request" do
	request_body = %{
	"user" => %{
	"id" => 123,
	"name" => "*1234",
	"email" => "foo@bar.com",
	"updated_at" => "2017-09-12T14:44:55Z"
	}
	}

	conn =
	:post
	\|> Plug.Test.conn("/api/users", Poison.encode!(request_body))
	\|> Plug.Conn.put_req_header("content-type", "application/json")

	conn = OpenApiSpexTest.Router.call(conn, [])
	assert conn.status == 422
	assert conn.resp_body == "#/user/name: Value does not match pattern: [a-zA-Z][a-zA-Z0-9_]+"
	end
	end
	-end
	\ No newline at end of file
	+end
	diff --git a/test/param_test.exs b/test/param_test.exs
	index 7580d7b..d2358fc 100644
	--- a/test/param_test.exs
	+++ b/test/param_test.exs
	@@ -1,70 +1,85 @@
	defmodule ParamTest do
	use ExUnit.Case

	describe "Param" do
	test "Valid Param" do
	conn =
	:get
	\|> Plug.Test.conn("/api/users?validParam=true")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 200
	end

	test "Invalid value" do
	conn =
	:get
	\|> Plug.Test.conn("/api/users?validParam=123")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 422
	end

	test "Invalid Param" do
	conn =
	:get
	\|> Plug.Test.conn("/api/users?validParam=123&inValidParam=123&inValid2=hi")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 422
	assert conn.resp_body == "Undefined query parameter: \"inValid2\""
	end
	+
	+ test "with requestBody" do
	+ body = Poison.encode!(%{
	+ phone_number: "123-456-789",
	+ postal_address: "123 Lane St"
	+ })
	+
	+ conn =
	+ :post
	+ \|> Plug.Test.conn("/api/users/123/contact_info", body)
	+ \|> Plug.Conn.put_req_header("content-type", "application/json")
	+ \|> OpenApiSpexTest.Router.call([])
	+
	+ assert conn.status == 200
	+ end
	end

	describe "Param with custom error handling" do
	test "Valid Param" do
	conn =
	:get
	\|> Plug.Test.conn("/api/custom_error_users?validParam=true")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 200
	end

	test "Invalid value" do
	conn =
	:get
	\|> Plug.Test.conn("/api/custom_error_users?validParam=123")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 400
	end

	test "Invalid Param" do
	conn =
	:get
	\|> Plug.Test.conn("/api/custom_error_users?validParam=123&inValidParam=123&inValid2=hi")
	\|> Plug.Conn.put_req_header("content-type", "application/json")
	\|> OpenApiSpexTest.Router.call([])

	assert conn.status == 400
	assert conn.resp_body == "Undefined query parameter: \"inValid2\""
	end
	end

	end
	diff --git a/test/support/router.ex b/test/support/router.ex
	index 48f0328..6fe3658 100644
	--- a/test/support/router.ex
	+++ b/test/support/router.ex
	@@ -1,22 +1,23 @@
	defmodule OpenApiSpexTest.Router do
	use Phoenix.Router
	alias Plug.Parsers
	alias OpenApiSpexTest.UserController
	alias OpenApiSpexTest.CustomErrorUserController
	alias OpenApiSpex.Plug.{PutApiSpec, RenderSpec}

	pipeline :api do
	plug :accepts, ["json"]
	plug PutApiSpec, module: OpenApiSpexTest.ApiSpec
	plug Parsers, parsers: [:json], pass: ["text/*"], json_decoder: Poison
	end

	scope "/api" do
	pipe_through :api
	resources "/users", UserController, only: [:create, :index, :show]
	resources "/custom_error_users", CustomErrorUserController, only: [:index]
	get "/users/:id/payment_details", UserController, :payment_details
	+ post "/users/:id/contact_info", UserController, :contact_info
	post "/users/create_entity", UserController, :create_entity
	get "/openapi", RenderSpec, []
	end
	end
	diff --git a/test/support/schemas.ex b/test/support/schemas.ex
	index 3c48c66..1f0436a 100644
	--- a/test/support/schemas.ex
	+++ b/test/support/schemas.ex
	@@ -1,228 +1,245 @@
	defmodule OpenApiSpexTest.Schemas do
	require OpenApiSpex
	alias OpenApiSpex.Schema

	defmodule User do
	OpenApiSpex.schema %{
	title: "User",
	description: "A user of the app",
	type: :object,
	properties: %{
	id: %Schema{type: :integer, description: "User ID"},
	name: %Schema{type: :string, description: "User name", pattern: ~r/[a-zA-Z][a-zA-Z0-9_]+/},
	email: %Schema{type: :string, description: "Email address", format: :email},
	inserted_at: %Schema{type: :string, description: "Creation timestamp", format: :'date-time'},
	updated_at: %Schema{type: :string, description: "Update timestamp", format: :'date-time'}
	},
	required: [:name, :email],
	additionalProperties: false,
	example: %{
	"id" => 123,
	"name" => "Joe User",
	"email" => "joe@gmail.com",
	"inserted_at" => "2017-09-12T12:34:55Z",
	"updated_at" => "2017-09-13T10:11:12Z"
	}
	}
	end

	+ defmodule ContactInfo do
	+ OpenApiSpex.schema %{
	+ title: "ContactInfo",
	+ description: "A users contact information",
	+ type: :object,
	+ properties: %{
	+ phone_number: %Schema{type: :string, description: "Phone number"},
	+ postal_address: %Schema{type: :string, description: "Postal address"}
	+ },
	+ required: [:phone_number],
	+ additionalProperties: false,
	+ example: %{
	+ "phone_number" => "555-123-456",
	+ "postal_address" => "123 Evergreen Tce"
	+ }
	+ }
	+ end
	+
	defmodule CreditCardPaymentDetails do
	OpenApiSpex.schema %{
	title: "CreditCardPaymentDetails",
	description: "Payment details when using credit-card method",
	type: :object,
	properties: %{
	credit_card_number: %Schema{type: :string, description: "Credit card number"},
	name_on_card: %Schema{type: :string, description: "Name as appears on card"},
	expiry: %Schema{type: :string, description: "4 digit expiry MMYY"}
	},
	required: [:credit_card_number, :name_on_card, :expiry],
	example: %{
	"credit_card_number" => "1234-5678-1234-6789",
	"name_on_card" => "Joe User",
	"expiry" => "1234"
	}
	}
	end

	defmodule DirectDebitPaymentDetails do
	OpenApiSpex.schema %{
	title: "DirectDebitPaymentDetails",
	description: "Payment details when using direct-debit method",
	type: :object,
	properties: %{
	account_number: %Schema{type: :string, description: "Bank account number"},
	account_name: %Schema{type: :string, description: "Name of account"},
	bsb: %Schema{type: :string, description: "Branch identifier"}
	},
	required: [:account_number, :account_name, :bsb],
	example: %{
	"account_number" => "12349876",
	"account_name" => "Joes Savings Account",
	"bsb" => "123-4567"
	}
	}
	end

	defmodule PaymentDetails do
	OpenApiSpex.schema %{
	title: "PaymentDetails",
	description: "Abstract Payment details type",
	type: :object,
	oneOf: [
	CreditCardPaymentDetails,
	DirectDebitPaymentDetails
	]
	}
	end

	defmodule UserRequest do
	OpenApiSpex.schema %{
	title: "UserRequest",
	description: "POST body for creating a user",
	type: :object,
	properties: %{
	user: User
	},
	example: %{
	"user" => %{
	"name" => "Joe User",
	"email" => "joe@gmail.com"
	}
	}
	}
	end

	defmodule UserResponse do
	OpenApiSpex.schema %{
	title: "UserResponse",
	description: "Response schema for single user",
	type: :object,
	properties: %{
	data: User
	},
	example: %{
	"data" => %{
	"id" => 123,
	"name" => "Joe User",
	"email" => "joe@gmail.com",
	"inserted_at" => "2017-09-12T12:34:55Z",
	"updated_at" => "2017-09-13T10:11:12Z"
	}
	- },
	- "x-struct": __MODULE__
	+ }
	}
	end

	defmodule UsersResponse do
	OpenApiSpex.schema %{
	title: "UsersResponse",
	description: "Response schema for multiple users",
	type: :object,
	properties: %{
	data: %Schema{description: "The users details", type: :array, items: User}
	},
	example: %{
	"data" => [
	%{
	"id" => 123,
	"name" => "Joe User",
	"email" => "joe@gmail.com"
	},
	%{
	"id" => 456,
	"name" => "Jay Consumer",
	"email" => "jay@yahoo.com"
	}
	]
	}
	}
	end

	defmodule EntityWithDict do
	OpenApiSpex.schema %{
	title: "EntityWithDict",
	description: "Entity with a dictionary defined via additionalProperties",
	type: :object,
	properties: %{
	id: %Schema{type: :integer, description: "Entity ID"},
	stringDict: %Schema{type: :object, description: "String valued dict", additionalProperties: %Schema{type: :string}},
	anyTypeDict: %Schema{type: :object, description: "Untyped valued dict", additionalProperties: true},
	},
	example: %{
	"id" => 123,
	"stringDict" => %{"key1" => "value1", "key2" => "value2"},
	"anyTypeDict" => %{"key1" => 42, "key2" => %{"foo" => "bar"}}
	}
	}
	end

	defmodule Pet do
	require OpenApiSpex

	alias OpenApiSpex.{Schema, Discriminator}

	OpenApiSpex.schema(%{
	title: "Pet",
	type: :object,
	properties: %{
	pet_type: %Schema{type: :string}
	},
	required: [:pet_type],
	discriminator: %Discriminator{
	propertyName: "pet_type"
	}
	})
	end

	defmodule Cat do
	require OpenApiSpex

	alias OpenApiSpex.Schema

	OpenApiSpex.schema(%{
	title: "Cat",
	type: :object,
	allOf: [
	Pet,
	%Schema{
	type: :object,
	properties: %{
	meow: %Schema{type: :string}
	},
	required: [:meow]
	}
	]
	})
	end

	defmodule Dog do
	require OpenApiSpex

	alias OpenApiSpex.Schema

	OpenApiSpex.schema(%{
	title: "Dog",
	type: :object,
	allOf: [
	Pet,
	%Schema{
	type: :object,
	properties: %{
	bark: %Schema{type: :string}
	},
	required: [:bark]
	}
	]
	})
	end

	defmodule CatOrDog do
	require OpenApiSpex

	OpenApiSpex.schema(%{
	title: "CatOrDog",
	oneOf: [Cat, Dog]
	})
	end
	end
	diff --git a/test/support/user_controller.ex b/test/support/user_controller.ex
	index 9a92a8f..1c48db5 100644
	--- a/test/support/user_controller.ex
	+++ b/test/support/user_controller.ex
	@@ -1,140 +1,164 @@
	defmodule OpenApiSpexTest.UserController do
	use Phoenix.Controller
	alias OpenApiSpex.Operation
	alias OpenApiSpexTest.Schemas

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

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

	@doc """
	API Spec for :show action
	"""
	def show_operation() do
	import Operation
	%Operation{
	tags: ["users"],
	summary: "Show user",
	description: "Show a user by ID",
	operationId: "UserController.show",
	parameters: [
	parameter(:id, :path, :integer, "User ID", example: 123, minimum: 1)
	],
	responses: %{
	200 => response("User", "application/json", Schemas.UserResponse)
	}
	}
	end
	def show(conn, %{id: id}) do
	json(conn, %Schemas.UserResponse{
	data: %Schemas.User{
	id: id,
	name: "joe user",
	email: "joe@gmail.com"
	}
	})
	end

	def index_operation() do
	import Operation
	%Operation{
	tags: ["users"],
	summary: "List users",
	description: "List all useres",
	operationId: "UserController.index",
	parameters: [
	parameter(:validParam, :query, :boolean, "Valid Param", example: true)
	],
	responses: %{
	200 => response("User List Response", "application/json", Schemas.UsersResponse)
	}
	}
	end
	def index(conn, _params) do
	json(conn, %Schemas.UsersResponse{
	data: [
	%Schemas.User{
	id: 123,
	name: "joe user",
	email: "joe@gmail.com"
	}
	]
	})
	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", Schemas.UserRequest),
	responses: %{
	201 => response("User", "application/json", Schemas.UserResponse)
	}
	}
	end
	- def create(conn, %Schemas.UserRequest{user: user = %Schemas.User{}}) do
	+ def create(conn = %{body_params: %Schemas.UserRequest{user: user = %Schemas.User{}}}, _) do
	json(conn, %Schemas.UserResponse{
	data: %{user \| id: 1234}
	})
	end

	+ def contact_info_operation() do
	+ import Operation
	+ %Operation{
	+ tags: ["users"],
	+ summary: "Update contact info",
	+ description: "Update contact info",
	+ operationId: "UserController.contact_info",
	+ parameters: [
	+ parameter(:id, :path, :integer, "user ID")
	+ ],
	+ requestBody: request_body("Contact info", "application/json", Schemas.ContactInfo),
	+ responses: %{
	+ 200 => %OpenApiSpex.Response{
	+ description: "OK"
	+ }
	+ }
	+ }
	+ end
	+ def contact_info(conn = %{body_params: %Schemas.ContactInfo{}}, %{id: id}) do
	+ conn
	+ \|> put_status(200)
	+ \|> json(%{id: id})
	+ end
	+
	def payment_details_operation() do
	import Operation
	%Operation{
	tags: ["users"],
	summary: "Show user payment details",
	description: "Shows a users payment details",
	operationId: "UserController.payment_details",
	parameters: [
	parameter(:id, :path, :integer, "User ID", example: 123, minimum: 1)
	],
	responses: %{
	200 => response("Payment Details", "application/json", Schemas.PaymentDetails)
	}
	}
	end
	def payment_details(conn, %{"id" => id}) do
	response =
	case rem(id, 2) do
	0 ->
	%Schemas.CreditCardPaymentDetails{
	credit_card_number: "1234-5678-0987-6543",
	name_on_card: "Joe User",
	expiry: "0522"
	}
	1 ->
	%Schemas.DirectDebitPaymentDetails{
	account_number: "98776543",
	account_name: "Joes Savings",
	bsb: "123-567"
	}
	end

	json(conn, response)
	end

	def create_entity_operation() do
	import Operation
	%Operation{
	tags: ["EntityWithDict"],
	summary: "Create an EntityWithDict",
	description: "Create an EntityWithDict",
	operationId: "UserController.create_entity",
	parameters: [],
	requestBody: request_body("Entity attributes", "application/json", Schemas.EntityWithDict),
	responses: %{
	201 => response("EntityWithDict", "application/json", Schemas.EntityWithDict)
	}
	}
	end
	def create_entity(conn, %Schemas.EntityWithDict{} = entity) do
	json(conn, Map.put(entity, :id, 123))
	end
	end

File Metadata

Mime Type: text/x-diff
Expires: Sun, Dec 1, 6:53 PM (1 d, 15 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 41812
Default Alt Text: (44 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions