No OneTemporary
Actions

Size

45 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/README.md b/README.md
	index a89e82d..be4837b 100644
	--- a/README.md
	+++ b/README.md
	@@ -1,289 +1,296 @@
	# 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.1"}
	]
	end
	```

	## Generate Spec

	-Start by adding an `ApiSpec` module to your application.
	+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.
	+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 export a `schema/0` function, and may optionally declare a struct,
	-linked to the JSON schema through the `x-struct` extension property.
	+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.

	```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: [],
	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
	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 09d35de..f459e91 100644
	--- a/lib/open_api_spex.ex
	+++ b/lib/open_api_spex.ex
	@@ -1,99 +1,123 @@
	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 Schema or Operation spec.
	+ 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 \| Operation.t, any) :: {:ok, any} \| {:error, String.t}
	+ @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`.
	+
	+ `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}
	+ 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 a Schema or Operation spec.
	+ 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 OpenApiSpex Schema
	+ 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/schema.ex b/lib/open_api_spex/schema.ex
	index 4609f9b..8e9917d 100644
	--- a/lib/open_api_spex/schema.ex
	+++ b/lib/open_api_spex/schema.ex
	@@ -1,475 +1,620 @@
	defmodule OpenApiSpex.Schema do
	@moduledoc """
	Defines the `OpenApiSpex.Schema.t` type and operations for casting and validating against a schema.
	+
	+ The `OpenApiSpex.schema` macro can be used to declare schemas with an associated struct and `Poison.Encoder`.
	+
	+ ## Examples
	+
	+ defmodule MyApp.Schemas do
	+ defmodule EmailString do
	+ @behaviour OpenApiSpex.Schema
	+ def schema do
	+ %OpenApiSpex.Schema {
	+ title: "EmailString",
	+ type: :string,
	+ format: :email
	+ }
	+ end
	+ end
	+
	+ defmodule Person do
	+ require OpenApiSpex
	+ alias OpenApiSpex.{Reference, Schema}
	+
	+ OpenApiSpex.schema(%{
	+ type: :object,
	+ required: [:name],
	+ properties: %{
	+ name: %Schema{type: :string},
	+ address: %Reference{"$ref": "#components/schemas/Address"},
	+ age: %Schema{type: :integer, format: :int32, minimum: 0}
	+ }
	+ })
	+ end
	+
	+ defmodule StringDictionary do
	+ @behaviour OpenApiSpex.Schema
	+
	+ def schema() do
	+ %OpenApiSpex.Schema{
	+ type: :object,
	+ additionalProperties: %{
	+ type: :string
	+ }
	+ }
	+ end
	+ end
	+
	+ defmodule Pet do
	+ require OpenApiSpex
	+ alias OpenApiSpex.{Schema, Discriminator}
	+
	+ OpenApiSpex.schema(%{
	+ title: "Pet",
	+ type: :object,
	+ discriminator: %Discriminator{
	+ propertyName: "petType"
	+ },
	+ properties: %{
	+ name: %Schema{type: :string},
	+ petType: %Schema{type: :string}
	+ },
	+ required: [:name, :petType]
	+ })
	+ end
	+
	+ defmodule Cat do
	+ require OpenApiSpex
	+ alias OpenApiSpex.Schema
	+
	+ OpenApiSpex.schema(%{
	+ title: "Cat",
	+ type: :object,
	+ description: "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
	+ allOf: [
	+ Pet,
	+ %Schema{
	+ type: :object,
	+ properties: %{
	+ huntingSkill: %Schema{
	+ type: :string,
	+ description: "The measured skill for hunting",
	+ default: "lazy",
	+ enum: ["clueless", "lazy", "adventurous", "aggresive"]
	+ }
	+ },
	+ required: [:huntingSkill]
	+ }
	+ ]
	+ })
	+ end
	+
	+ defmodule Dog do
	+ require OpenApiSpex
	+ alias OpenApiSpex.Schema
	+
	+ OpenApiSpex.schema(%{
	+ type: :object,
	+ title: "Dog",
	+ description: "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
	+ allOf: [
	+ Pet,
	+ %Schema {
	+ type: :object,
	+ properties: %{
	+ packSize: %Schema{
	+ type: :integer,
	+ format: :int32,
	+ description: "the size of the pack the dog is from",
	+ default: 0,
	+ minimum: 0
	+ }
	+ },
	+ required: [
	+ :packSize
	+ ]
	+ }
	+ ]
	+ })
	+ end
	+ end
	"""

	alias OpenApiSpex.{
	Schema, Reference, Discriminator, Xml, ExternalDocumentation
	}

	@doc """
	A module implementing the `OpenApiSpex.Schema` behaviour should export a `schema/0` function
	that produces an `OpenApiSpex.Schema` struct.
	"""
	@callback schema() :: t

	defstruct [
	:title,
	:multipleOf,
	:maximum,
	:exclusiveMaximum,
	:minimum,
	:exclusiveMinimum,
	:maxLength,
	:minLength,
	:pattern,
	:maxItems,
	:minItems,
	:uniqueItems,
	:maxProperties,
	:minProperties,
	:required,
	:enum,
	:type,
	:allOf,
	:oneOf,
	:anyOf,
	:not,
	:items,
	:properties,
	:additionalProperties,
	:description,
	:format,
	:default,
	:nullable,
	:discriminator,
	:readOnly,
	:writeOnly,
	:xml,
	:externalDocs,
	:example,
	:deprecated,
	:"x-struct"
	]

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

	The Schema Object allows the definition of input and output data types.
	These types can be objects, but also primitives and arrays.
	This object is an extended subset of the JSON Schema Specification Wright Draft 00.

	## Example
	alias OpenApiSpex.Schema

	%Schema{
	title: "User",
	type: :object,
	properties: %{
	id: %Schema{type: :integer, minimum: 1},
	name: %Schema{type: :string, pattern: "[a-zA-Z][a-zA-Z0-9_]+"},
	email: %Scheam{type: :string, format: :email},
	last_login: %Schema{type: :string, format: :"date-time"}
	},
	required: [:name, :email],
	example: %{
	"name" => "joe",
	"email" => "joe@gmail.com"
	}
	}
	"""
	@type t :: %__MODULE__{
	title: String.t \| nil,
	multipleOf: number \| nil,
	maximum: number \| nil,
	exclusiveMaximum: boolean \| nil,
	minimum: number \| nil,
	exclusiveMinimum: boolean \| nil,
	maxLength: integer \| nil,
	minLength: integer \| nil,
	pattern: String.t \| Regex.t \| nil,
	maxItems: integer \| nil,
	minItems: integer \| nil,
	uniqueItems: boolean \| nil,
	maxProperties: integer \| nil,
	minProperties: integer \| nil,
	required: [atom] \| nil,
	enum: [String.t] \| nil,
	type: atom \| nil,
	allOf: [Schema.t \| Reference.t \| module] \| nil,
	oneOf: [Schema.t \| Reference.t \| module] \| nil,
	anyOf: [Schema.t \| Reference.t \| module] \| nil,
	not: Schema.t \| Reference.t \| module \| nil,
	items: Schema.t \| Reference.t \| module \| nil,
	properties: %{atom => Schema.t \| Reference.t \| module} \| nil,
	additionalProperties: boolean \| Schema.t \| Reference.t \| module \| nil,
	description: String.t \| nil,
	format: String.t \| atom \| nil,
	default: any,
	nullable: boolean \| nil,
	discriminator: Discriminator.t \| nil,
	readOnly: boolean \| nil,
	writeOnly: boolean \| nil,
	xml: Xml.t \| nil,
	externalDocs: ExternalDocumentation.t \| nil,
	example: any,
	deprecated: boolean \| nil,
	"x-struct": module \| nil
	}

	@doc """
	Cast a simple value to the elixir type defined by a schema.

	By default, object types are cast to maps, however if the "x-struct" attribute is set in the schema,
	the result will be constructed as an instance of the given struct type.

	## Examples

	iex> OpenApiSpex.Schema.cast(%Schema{type: :integer}, "123", %{})
	{:ok, 123}

	iex> {:ok, dt = %DateTime{}} = OpenApiSpex.Schema.cast(%Schema{type: :string, format: :"date-time"}, "2018-04-02T13:44:55Z", %{})
	...> dt \|> DateTime.to_iso8601()
	"2018-04-02T13:44:55Z"
	+
	+ ## Casting Polymorphic Schemas
	+
	+ Schemas using `discriminator`, `allOf`, `oneOf`, `anyOf` are cast using the following rules:
	+
	+ - If a `discriminator` is present, cast the properties defined in the base schema, then
	+ cast the result using the schema identified by the discriminator. To avoid infinite recursion,
	+ the discriminator is only dereferenced if the discriminator property has not already been cast.
	+
	+ - Cast the properties using each schema listing in `allOf`. When a property is defined in
	+ multiple `allOf` schemas, it will be cast using the first schema listed containing the property.
	+
	+ - Cast the value using each schema listed in `oneOf`, stopping as soon as a sucessful cast is made.
	+
	+ - Cast the value using each schema listed in `anyOf`, stopping as soon as a succesful cast is made.
	"""
	def cast(%Schema{type: :boolean}, value, _schemas) when is_boolean(value), do: {:ok, value}
	def cast(%Schema{type: :boolean}, value, _schemas) when is_binary(value) do
	case value do
	"true" -> {:ok, true}
	"false" -> {:ok, false}
	_ -> {:error, "Invalid boolean: #{inspect(value)}"}
	end
	end
	def cast(%Schema{type: :integer}, value, _schemas) when is_integer(value), do: {:ok, value}
	def cast(%Schema{type: :integer}, value, _schemas) when is_binary(value) do
	case Integer.parse(value) do
	{i, ""} -> {:ok, i}
	_ -> {:error, :bad_integer}
	end
	end
	def cast(%Schema{type: :number}, value, _schemas) when is_number(value), do: {:ok, value}
	def cast(%Schema{type: :number}, value, _schemas) when is_binary(value) do
	case Float.parse(value) do
	{x, ""} -> {:ok, x}
	_ -> {:error, :bad_float}
	end
	end
	def cast(%Schema{type: :string, format: :"date-time"}, value, _schemas) when is_binary(value) do
	case DateTime.from_iso8601(value) do
	{:ok, datetime = %DateTime{}, _offset} -> {:ok, datetime}
	error = {:error, _reason} -> error
	end
	end
	def cast(%Schema{type: :string, format: :date}, value, _schemas) when is_binary(value) do
	case Date.from_iso8601(value) do
	{:ok, date = %Date{}} -> {:ok, date}
	error = {:error, _reason} -> error
	end
	end
	def cast(%Schema{type: :string}, value, _schemas) when is_binary(value), do: {:ok, value}
	def cast(%Schema{type: :array, items: nil}, value, _schemas) when is_list(value), do: {:ok, value}
	def cast(%Schema{type: :array}, [], _schemas), do: {:ok, []}
	def cast(schema = %Schema{type: :array, items: items_schema}, [x \| rest], schemas) do
	with {:ok, x_cast} <- cast(items_schema, x, schemas),
	{:ok, rest_cast} <- cast(schema, rest, schemas) do
	{:ok, [x_cast \| rest_cast]}
	end
	end
	def cast(%Schema{type: :array}, value, _schemas) when not is_list(value) do
	{:error, "Invalid array: #{inspect(value)}"}
	end
	def cast(schema = %Schema{type: :object, discriminator: discriminator = %{}}, value = %{}, schemas) do
	discriminator_property = String.to_existing_atom(discriminator.propertyName)
	already_cast? =
	if Map.has_key?(value, discriminator_property) do
	{:error, :already_cast}
	else
	:ok
	end

	with :ok <- already_cast?,
	{:ok, partial_cast} <- cast(%Schema{type: :object, properties: schema.properties}, value, schemas),
	{:ok, derived_schema} <- Discriminator.resolve(discriminator, value, schemas),
	{:ok, result} <- cast(derived_schema, partial_cast, schemas) do
	{:ok, make_struct(result, schema)}
	else
	{:error, :already_cast} -> {:ok, value}
	{:error, reason} -> {:error, reason}
	end
	end
	def cast(schema = %Schema{type: :object, allOf: [first \| rest]}, value = %{}, schemas) do
	with {:ok, cast_first} <- cast(first, value, schemas),
	{:ok, result} <- cast(%{schema \| allOf: rest}, cast_first, schemas) do
	{:ok, result}
	else
	{:error, reason} -> {:error, reason}
	end
	end
	def cast(schema = %Schema{type: :object, allOf: []}, value = %{}, schemas) do
	cast(%{schema \| allOf: nil}, value, schemas)
	end
	- def cast(schema = %Schema{oneOf: [first\|rest]}, value, schemas) do
	+ def cast(schema = %Schema{oneOf: [first \| rest]}, value, schemas) do
	case cast(first, value, schemas) do
	{:ok, result} ->
	cast(%{schema \| oneOf: nil}, result, schemas)
	{:error, _reason} ->
	cast(%{schema \| oneOf: rest}, value, schemas)
	end
	end
	def cast(%Schema{oneOf: []}, _value, _schemas) do
	{:error, "Failed to cast to any schema in oneOf"}
	end

	+ def cast(schema = %Schema{anyOf: [first \| rest]}, value, schemas) do
	+ case cast(first, value, schemas) do
	+ {:ok, result} ->
	+ cast(%{schema \| anyOf: nil}, result, schemas)
	+ {:error, _reason} ->
	+ cast(%{schema \| anyOf: rest}, value, schemas)
	+ end
	+ end
	+ def cast(%Schema{oneOf: []}, _value, _schemas) do
	+ {:error, "Failed to cast to any schema in oneOf"}
	+ end
	+
	def cast(schema = %Schema{type: :object}, value, schemas) when is_map(value) do
	schema = %{schema \| properties: schema.properties \|\| %{}}
	{regular_properties, others} =
	value
	\|> no_struct()
	\|> Enum.split_with(fn {k, _v} -> is_binary(k) end)

	with {:ok, props} <- cast_properties(schema, regular_properties, schemas) do
	result = Map.new(others ++ props) \|> make_struct(schema)
	{:ok, result}
	end
	end
	def cast(ref = %Reference{}, val, schemas), do: cast(Reference.resolve_schema(ref, schemas), val, schemas)
	def cast(_additionalProperties = false, val, _schemas) do
	{:error, "Unexpected field with value #{inspect(val)}"}
	end
	def cast(_additionalProperties, val, _schemas), do: {:ok, val}

	defp make_struct(val = %_{}, _), do: val
	defp make_struct(val, %{"x-struct": nil}), do: val
	defp make_struct(val, %{"x-struct": mod}) do
	Enum.reduce(val, struct(mod), fn {k, v}, acc ->
	Map.put(acc, k, v)
	end)
	end

	defp no_struct(val), do: Map.delete(val, :__struct__)

	@spec cast_properties(Schema.t, list, %{String.t => Schema.t}) :: {:ok, list} \| {:error, String.t}
	defp cast_properties(%Schema{}, [], _schemas), do: {:ok, []}
	defp cast_properties(object_schema = %Schema{}, [{key, value} \| rest], schemas) do
	{name, schema} = Enum.find(
	object_schema.properties,
	{key, object_schema.additionalProperties},
	fn {name, _schema} -> to_string(name) == to_string(key) end)

	with {:ok, new_value} <- cast(schema, value, schemas),
	{:ok, cast_tail} <- cast_properties(object_schema, rest, schemas) do
	{:ok, [{name, new_value} \| cast_tail]}
	end
	end

	@doc """
	Validate a value against a Schema.

	This expects that the value has already been `cast` to the appropriate data type.

	## Examples

	iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :integer, minimum: 5}, 3, %{})
	{:error, "#: 3 is smaller than minimum 5"}

	iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.)@(.)"}, "joe@gmail.com", %{})
	:ok

	iex> OpenApiSpex.Schema.validate(%OpenApiSpex.Schema{type: :string, pattern: "(.)@(.)"}, "joegmail.com", %{})
	{:error, "#: Value does not match pattern: (.)@(.)"}
	"""
	@spec validate(Schema.t \| Reference.t, any, %{String.t => Schema.t \| Reference.t}) :: :ok \| {:error, String.t}
	def validate(schema, val, schemas), do: validate(schema, val, "#", schemas)

	@spec validate(Schema.t \| Reference.t, any, String.t, %{String.t => Schema.t \| Reference.t}) :: :ok \| {:error, String.t}
	def validate(ref = %Reference{}, val, path, schemas), do: validate(Reference.resolve_schema(ref, schemas), val, path, schemas)
	def validate(%Schema{nullable: true}, nil, _path, _schemas), do: :ok
	def validate(%Schema{type: type}, nil, path, _schemas) do
	{:error, "#{path}: null value where #{type} expected"}
	end
	def validate(schema = %Schema{type: type}, value, path, _schemas) when type in [:integer, :number] do
	with :ok <- validate_multiple(schema, value, path),
	:ok <- validate_maximum(schema, value, path),
	:ok <- validate_minimum(schema, value, path) do
	:ok
	end
	end
	def validate(schema = %Schema{type: :string}, value, path, _schemas) do
	with :ok <- validate_max_length(schema, value, path),
	:ok <- validate_min_length(schema, value, path),
	:ok <- validate_pattern(schema, value, path) do
	:ok
	end
	end
	def validate(%Schema{type: :boolean}, value, path, _schemas) do
	case is_boolean(value) do
	true -> :ok
	_ -> {:error, "#{path}: Invalid boolean: #{inspect(value)}"}
	end
	end
	def validate(schema = %Schema{type: :array}, value, path, schemas) do
	with :ok <- validate_max_items(schema, value, path),
	:ok <- validate_min_items(schema, value, path),
	:ok <- validate_unique_items(schema, value, path),
	:ok <- validate_array_items(schema, value, {path, 0}, schemas) do
	:ok
	end
	end
	def validate(schema = %Schema{type: :object}, value = %{}, path, schemas) do
	schema = %{schema \| properties: schema.properties \|\| %{}, required: schema.required \|\| []}
	with :ok <- validate_required_properties(schema, value, path),
	:ok <- validate_max_properties(schema, value, path),
	:ok <- validate_min_properties(schema, value, path),
	:ok <- validate_object_properties(schema.properties, MapSet.new(schema.required), value, path, schemas) do
	:ok
	end
	end

	@spec validate_multiple(Schema.t, number, String.t) :: :ok \| {:error, String.t}
	defp validate_multiple(%{multipleOf: nil}, _, _), do: :ok
	defp validate_multiple(%{multipleOf: n}, value, _) when (round(value / n) * n == value), do: :ok
	defp validate_multiple(%{multipleOf: n}, value, path), do: {:error, "#{path}: #{value} is not a multiple of #{n}"}

	@spec validate_maximum(Schema.t, number, String.t) :: :ok \| {:error, String.t}
	defp validate_maximum(%{maximum: nil}, _val, _path), do: :ok
	defp validate_maximum(%{maximum: n, exclusiveMaximum: true}, value, _path) when value < n, do: :ok
	defp validate_maximum(%{maximum: n}, value, _path) when value <= n, do: :ok
	defp validate_maximum(%{maximum: n}, value, path), do: {:error, "#{path}: #{value} is larger than maximum #{n}"}

	@spec validate_minimum(Schema.t, number, String.t) :: :ok \| {:error, String.t}
	defp validate_minimum(%{minimum: nil}, _val, _path), do: :ok
	defp validate_minimum(%{minimum: n, exclusiveMinimum: true}, value, _path) when value > n, do: :ok
	defp validate_minimum(%{minimum: n}, value, _path) when value >= n, do: :ok
	defp validate_minimum(%{minimum: n}, value, path), do: {:error, "#{path}: #{value} is smaller than minimum #{n}"}

	@spec validate_max_length(Schema.t, String.t, String.t) :: :ok \| {:error, String.t}
	defp validate_max_length(%{maxLength: nil}, _val, _path), do: :ok
	defp validate_max_length(%{maxLength: n}, value, path) do
	case String.length(value) <= n do
	true -> :ok
	_ -> {:error, "#{path}: String length is larger than maxLength: #{n}"}
	end
	end

	@spec validate_min_length(Schema.t, String.t, String.t) :: :ok \| {:error, String.t}
	defp validate_min_length(%{minLength: nil}, _val, _path), do: :ok
	defp validate_min_length(%{minLength: n}, value, path) do
	case String.length(value) >= n do
	true -> :ok
	_ -> {:error, "#{path}: String length is smaller than minLength: #{n}"}
	end
	end

	@spec validate_pattern(Schema.t, String.t, String.t) :: :ok \| {:error, String.t}
	defp validate_pattern(%{pattern: nil}, _val, _path), do: :ok
	defp validate_pattern(schema = %{pattern: regex}, val, path) when is_binary(regex) do
	with {:ok, regex} <- Regex.compile(regex) do
	validate_pattern(%{schema \| pattern: regex}, val, path)
	end
	end
	defp validate_pattern(%{pattern: regex = %Regex{}}, val, path) do
	case Regex.match?(regex, val) do
	true -> :ok
	_ -> {:error, "#{path}: Value does not match pattern: #{regex.source}"}
	end
	end

	@spec validate_max_items(Schema.t, list, String.t) :: :ok \| {:error, String.t}
	defp validate_max_items(%Schema{maxItems: nil}, _val, _path), do: :ok
	defp validate_max_items(%Schema{maxItems: n}, value, _path) when length(value) <= n, do: :ok
	defp validate_max_items(%Schema{maxItems: n}, value, path) do
	{:error, "#{path}: Array length #{length(value)} is larger than maxItems: #{n}"}
	end

	@spec validate_min_items(Schema.t, list, String.t) :: :ok \| {:error, String.t}
	defp validate_min_items(%Schema{minItems: nil}, _val, _path), do: :ok
	defp validate_min_items(%Schema{minItems: n}, value, _path) when length(value) >= n, do: :ok
	defp validate_min_items(%Schema{minItems: n}, value, path) do
	{:error, "#{path}: Array length #{length(value)} is smaller than minItems: #{n}"}
	end

	@spec validate_unique_items(Schema.t, list, String.t) :: :ok \| {:error, String.t}
	defp validate_unique_items(%Schema{uniqueItems: true}, value, path) do
	unique_size =
	value
	\|> MapSet.new()
	\|> MapSet.size()

	case unique_size == length(value) do
	true -> :ok
	_ -> {:error, "#{path}: Array items must be unique"}
	end
	end
	defp validate_unique_items(_schema, _value, _path), do: :ok

	@spec validate_array_items(Schema.t, list, {String.t, integer}, %{String.t => Schema.t}) :: :ok \| {:error, String.t}
	defp validate_array_items(%Schema{type: :array, items: nil}, value, _path, _schemas) when is_list(value), do: :ok
	defp validate_array_items(%Schema{type: :array}, [], _path, _schemas), do: :ok
	defp validate_array_items(schema = %Schema{type: :array, items: item_schema}, [x \| rest], {path, index}, schemas) do
	with :ok <- validate(item_schema, x, "#{path}/#{index}", schemas) do
	validate_array_items(schema, rest, {path, index + 1}, schemas)
	end
	end

	@spec validate_required_properties(Schema.t, %{}, String.t) :: :ok \| {:error, String.t}
	defp validate_required_properties(%Schema{type: :object, required: nil}, _val, _path), do: :ok
	defp validate_required_properties(%Schema{type: :object, required: required}, value = %{}, path) do
	missing = required -- Map.keys(value)
	case missing do
	[] -> :ok
	_ -> {:error, "#{path}: Missing required properties: #{inspect(missing)}"}
	end
	end

	@spec validate_max_properties(Schema.t, %{}, String.t) :: :ok \| {:error, String.t}
	defp validate_max_properties(%Schema{type: :object, maxProperties: nil}, _val, _path), do: :ok
	defp validate_max_properties(%Schema{type: :object, maxProperties: n}, val, _path) when map_size(val) <= n, do: :ok
	defp validate_max_properties(%Schema{type: :object, maxProperties: n}, val, path) do
	{:error, "#{path}: Object property count #{map_size(val)} is greater than maxProperties: #{n}"}
	end

	@spec validate_min_properties(Schema.t, %{}, String.t) :: :ok \| {:error, String.t}
	defp validate_min_properties(%Schema{type: :object, minProperties: nil}, _val, _path), do: :ok
	defp validate_min_properties(%Schema{type: :object, minProperties: n}, val, _path) when map_size(val) >= n, do: :ok
	defp validate_min_properties(%Schema{type: :object, minProperties: n}, val, path) do
	{:error, "#{path}: Object property count #{map_size(val)} is less than minProperties: #{n}"}
	end

	@spec validate_object_properties(Enumerable.t, MapSet.t, %{}, String.t, %{String.t => Schema.t \| Reference.t}) :: :ok \| {:error, String.t}
	defp validate_object_properties(properties = %{}, required, value = %{}, path, schemas = %{}) do
	properties
	\|> Enum.filter(fn {name, _schema} -> Map.has_key?(value, name) end)
	\|> validate_object_properties(required, value, path, schemas)
	end
	defp validate_object_properties([], _required, _val, _path, _schemas), do: :ok
	defp validate_object_properties([{name, schema} \| rest], required, value = %{}, path, schemas = %{}) do
	property_required = MapSet.member?(required, name)
	property_value = Map.get(value, name)
	property_path = "#{path}/#{name}"
	with :ok <- validate_object_property(schema, property_required, property_value, property_path, schemas),
	:ok <- validate_object_properties(rest, required, value, path, schemas) do
	:ok
	end
	end
	defp validate_object_property(_schema, false, nil, _path, _schemas), do: :ok
	defp validate_object_property(schema, _required, value, path, schemas) do
	validate(schema, value, path, schemas)
	end

	@doc """
	Get the names of all properties definied for a schema.

	Includes all properties directly defined in the schema, and all schemas
	included in the `allOf` list.
	"""
	def properties(schema = %Schema{type: :object, properties: properties = %{}}) do
	Map.keys(properties) ++ properties(%{schema \| properties: nil})
	end
	def properties(%Schema{allOf: schemas}) when is_list(schemas) do
	Enum.flat_map(schemas, &properties/1) \|> Enum.uniq()
	end
	def properties(schema_module) when is_atom(schema_module) do
	properties(schema_module.schema())
	end
	def properties(_), do: []
	end
	diff --git a/lib/open_api_spex/test/assertions.ex b/lib/open_api_spex/test/assertions.ex
	index c59d59c..411019d 100644
	--- a/lib/open_api_spex/test/assertions.ex
	+++ b/lib/open_api_spex/test/assertions.ex
	@@ -1,26 +1,37 @@
	defmodule OpenApiSpex.Test.Assertions do
	@moduledoc """
	Defines helpers for testing API responses and examples against API spec schemas.
	"""
	alias OpenApiSpex.OpenApi
	import ExUnit.Assertions

	@dialyzer {:no_match, assert_schema: 3}

	@doc """
	Asserts that `value` conforms to the schema with title `schema_title` in `api_spec`.
	"""
	@spec assert_schema(map, String.t, OpenApi.t) :: map \| no_return
	def assert_schema(value = %{}, schema_title, api_spec = %OpenApi{}) do
	schemas = api_spec.components.schemas
	schema = schemas[schema_title]
	if !schema do
	flunk("Schema: #{schema_title} not found in #{inspect(Map.keys(schemas))}")
	end

	- _ = assert {:ok, data} = OpenApiSpex.cast(api_spec, schema, value)
	- _ = assert :ok = OpenApiSpex.validate(api_spec, schema, data)
	+
	+ data =
	+ case OpenApiSpex.cast(api_spec, schema, value) do
	+ {:ok, data} -> data
	+ {:error, reason} ->
	+ flunk("Value does not conform to schema #{schema_title}: #{reason}\n#{inspect value}")
	+ end
	+
	+ case OpenApiSpex.validate(api_spec, schema, data) do
	+ :ok -> :ok
	+ {:error, reason} ->
	+ flunk("Value does not conform to schema #{schema_title}: #{reason}\n#{inspect value}")
	+ end

	data
	end
	-end
	\ No newline at end of file
	+end
	diff --git a/test/schema_test.exs b/test/schema_test.exs
	index 0b72dce..4081a64 100644
	--- a/test/schema_test.exs
	+++ b/test/schema_test.exs
	@@ -1,116 +1,124 @@
	defmodule OpenApiSpex.SchemaTest do
	use ExUnit.Case
	alias OpenApiSpex.Schema
	alias OpenApiSpexTest.{ApiSpec, Schemas}
	import OpenApiSpex.Test.Assertions

	doctest Schema

	test "cast request schema" do
	api_spec = ApiSpec.spec()
	schemas = api_spec.components.schemas
	user_request_schema = schemas["UserRequest"]

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

	{:ok, output} = Schema.cast(user_request_schema, input, schemas)

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

	test "cast request schema with unexpected fields returns error" do
	api_spec = ApiSpec.spec()
	schemas = api_spec.components.schemas
	user_request_schema = schemas["UserRequest"]

	input = %{
	"user" => %{
	"id" => 123,
	"name" => "asdf",
	"email" => "foo@bar.com",
	"updated_at" => "2017-09-12T14:44:55Z",
	"unexpected_field" => "unexpected value"
	}
	}

	assert {:error, _} = Schema.cast(user_request_schema, input, schemas)
	end

	test "EntityWithDict Schema example matches schema" do
	api_spec = ApiSpec.spec()
	assert_schema(Schemas.EntityWithDict.schema().example, "EntityWithDict", api_spec)
	end

	test "User Schema example matches schema" do
	spec = ApiSpec.spec()
	assert_schema(Schemas.User.schema().example, "User", spec)
	assert_schema(Schemas.UserRequest.schema().example, "UserRequest", spec)
	assert_schema(Schemas.UserResponse.schema().example, "UserResponse", spec)
	assert_schema(Schemas.UsersResponse.schema().example, "UsersResponse", spec)
	end

	test "Cast Cat from Pet schema" do
	api_spec = ApiSpec.spec()
	schemas = api_spec.components.schemas
	pet_schema = schemas["Pet"]

	input = %{
	"pet_type" => "Cat",
	"meow" => "meow"
	}

	assert {:ok, %Schemas.Cat{meow: "meow", pet_type: "Cat"}} = Schema.cast(pet_schema, input, schemas)
	end

	test "Cast Dog from oneOf [cat, dog] schema" do
	api_spec = ApiSpec.spec()
	schemas = api_spec.components.schemas
	cat_or_dog = Map.fetch!(schemas, "CatOrDog")

	input = %{
	"pet_type" => "Cat",
	"meow" => "meow"
	}

	assert {:ok, %Schemas.Cat{meow: "meow", pet_type: "Cat"}} = Schema.cast(cat_or_dog, input, schemas)
	end

	test "Cast number to string or number" do
	schema = %Schema{
	oneOf: [
	%Schema{type: :number},
	%Schema{type: :string}
	]
	}

	result = Schema.cast(schema, "123", %{})

	assert {:ok, 123.0} = result
	end

	- @tag :focus
	- test "Cast string to number or datetime" do
	+ test "Cast string to oneOf number or datetime" do
	schema = %Schema{
	oneOf: [
	%Schema{type: :number},
	%Schema{type: :string, format: :"date-time"}
	]
	}
	assert {:ok, %DateTime{}} = Schema.cast(schema, "2018-04-01T12:34:56Z", %{})
	end

	+ test "Cast string to anyOf number or datetime" do
	+ schema = %Schema{
	+ oneOf: [
	+ %Schema{type: :number},
	+ %Schema{type: :string, format: :"date-time"}
	+ ]
	+ }
	+ assert {:ok, %DateTime{}} = Schema.cast(schema, "2018-04-01T12:34:56Z", %{})
	+ end
	end
	diff --git a/test/support/api_spec.ex b/test/support/api_spec.ex
	index abe0fe2..9b6611a 100644
	--- a/test/support/api_spec.ex
	+++ b/test/support/api_spec.ex
	@@ -1,34 +1,34 @@
	defmodule OpenApiSpexTest.ApiSpec do
	- alias OpenApiSpex.{OpenApi, Contact, License, Paths, Schema, Server, Info, Components}
	+ alias OpenApiSpex.{OpenApi, Contact, License, Paths, Server, Info, Components}
	alias OpenApiSpexTest.{Router, Schemas}

	def spec() do
	%OpenApi{
	servers: [
	%Server{url: "http://example.com"},
	],
	info: %Info{
	title: "A",
	version: "3.0",
	contact: %Contact{
	name: "joe",
	email: "Joe@gmail.com",
	url: "https://help.joe.com"
	},
	license: %License{
	name: "MIT",
	url: "http://mit.edu/license"
	}
	},
	components: %Components{
	schemas:
	for schemaMod <- [Schemas.Pet, Schemas.Cat, Schemas.Dog, Schemas.CatOrDog], into: %{} do
	schema = schemaMod.schema()
	{schema.title, schema}
	end
	},
	paths: Paths.from_router(Router)
	}
	\|> OpenApiSpex.resolve_schema_modules()
	end
	end

File Metadata

Mime Type: text/x-diff
Expires: Sun, Oct 11, 3:54 AM (1 d, 14 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 1785578
Default Alt Text: (45 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions