No OneTemporary
Actions

Size

21 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/CHANGELOG.md b/CHANGELOG.md
	index 2e8fd15..98d6a75 100644
	--- a/CHANGELOG.md
	+++ b/CHANGELOG.md
	@@ -1,197 +1,249 @@
	+# 3.4.0
	+
	+Thanks to the contributions of the community ❤️💙💛💜🧡
	+
	+ * [surik](https://github.com/surik)
	+ * [holsee](https://github.com/holsee)
	+ * [fmcgeough](https://github.com/fmcgeough)
	+
	+
	+ - Feature: the `OpenApiSpex` and `OpenApiSpex.Info` structs now support [extensions](https://swagger.io/docs/specification/openapi-extensions/) (#108) (#114)
	+
	+ The `extensions` key may contain any additional data that should be included in the info, eg the `x-logo` and `x-tagGroups` extensions:
	+
	+ ```elixir
	+ spec = %OpenApi{
	+ info: %Info{
	+ title: "Test",
	+ version: "1.0.0",
	+ extensions: %{
	+ "x-logo" => %{
	+ "url" => "https://example.com/logo.png",
	+ "backgroundColor" => "#FFFFFF",
	+ "altText" => "Example logo"
	+ }
	+ }
	+ },
	+ extensions: %{
	+ "x-tagGroups" => [
	+ %{
	+ "name" => "Methods",
	+ "tags" => [
	+ "Search",
	+ "Fetch",
	+ "Delete"
	+ ]
	+ }
	+ ]
	+ },
	+ paths: %{ ... }
	+ }
	+ ```
	+
	+ - Deprecation: `OpenApiSpex.Server.from_endpoint/2` has been deprecated in favor of `OpenApiSpex.Server.from_endpoint/1`.
	+ Simply remove the `otp_app:` option from the call to use the new function. (#116)
	+
	+```elixir
	+ # server = Server.from_endpoint(Endpoint, otp_app: :my_phoenix_app)
	+ server = Server.from_endpoint(MyPhoenixAppWeb.Endpoint)
	+```
	+
	+ - Fix: The internal representation of a Phoenix Route struct changed in Phoenix 1.4.7 breaking the `OpenApiSpex.Paths.from_router/1` function. OpenApiSpex 3.4.0 will support both representations until the Phoenix API becomes stable. (#118)
	+
	# 3.3.0

	Thanks to the contributions from the community! 👍

	* [hauleth](https://github.com/hauleth)
	* [cstaud](https://github.com/cstaud)
	* [xadhoom](https://github.com/xadhoom)
	* [nurugger07](https://github.com/nurugger07)
	* [fenollp](https://github.com/fenollp)
	* [moxley](https://github.com/moxley)

	- Feature: Enums expressed as atoms or atom-keyed maps can be cast from strings (or string-keyed maps). (#60) (#101)

	Example:

	```elixir
	parameters: [
	Operation.parameter(:sort, :query, :string, "sort direction", enum: [:asc, :desc])
	],
	```

	- Fix: Schema module references are resolved in in-line parameter/response schemas. (#77) (#105)

	Example: The response schema is given in-line as an array, but items are resolved from the `User` module.

	```elixir
	responses: %{
	200 => Operation.response(
	"User array",
	"application/json",
	%Schema{
	type: :array,
	items: MyApp.Schemas.User
	}
	)
	}
	```

	- Fix: Ensure integer query parameters are validated correctly after conversion from string. (#106)
	- Fix: Ensure integers are validated correctly against schema `minimum`, `maximum`, `exlcusiveMinimum` and `exclusiveMaximum` attributes. (#97)
	- Fix: Ensure strings are cast to `Date` or `DateTime` types when the schema format is `:date` or `:date-time`. (#90) (#94)
	- Docs: The contract for module supplied to the `PutApiSpec` plug is now documented by the `OpenApi` behaviour. (#73) (#103)
	- Docs: Poison replaced with Jason in example and tests (#104)
	- Docs: Improved documentation for combined `CastAndValidate` plug. (#91)
	- Internals: Cache mapping from phoenix controller/action to OpenApi operation. (#102)


	# 3.2.1

	Patch release for documentation updates and improved error rendering Plug when using `CastAndValidate`.

	Thanks [moxley](https://github.com/moxley)!

	- Cast and validate guide (#89)

	# 3.2.0

	This release contains many improvements and internal changes thanks to the contributions of the community!

	* [moxley](https://github.com/moxley)
	* [kpanic](https://github.com/kpanic)
	* [hauleth](https://github.com/hauleth)
	* [nurugger07](https://github.com/nurugger07)
	* [ggpasqualino](https://github.com/ggpasqualino)
	* [teamon](https://github.com/teamon)
	* [bryannaegele](https://github.com/bryannaegele)

	- Feature: Send Plug CSRF token in x-csrf-token header from Swagger UI (#82)
	- Feature: Support `Jason` library for JSON serialization (#75)
	- Feature: Combine casting and validation into a single `CastAndValidate` Plug (#69) (#86)
	- Feature: Improved performance by avoiding copying of API Spec data in each request (#83)
	- Fix: Convert `integers` to `float` when casting to `number` type (#81) (#84)
	- Fix: Validate strings without trimming whitespace first (#79)
	- Fix: Exclusive Minimum and Exclusive maximum are validated correctly (#68)
	- Fix: Report errors when unable to convert to the expected number/string/boolean type (#64)
	- Fix: Gracefully report error when failing to convert request params to an object type (#63)
	- Internals: Improved code organisation of unit test suite (#62)

	# 3.1.0

	- Add support for validating polymorphic schemas using `oneOf`, `anyOf`, `allOf`, `not` constructs.
	- Updated example apps to work with new API
	- CI has moved from travis-ci.org to travis-ci.com and now uses github apps integration.

	Thanks to [fenollp](https://github.com/fenollp) and [tapickell](https://github.com/tapickell) for contributions!

	# 3.0.0

	Major version bump as the behaviour of `OpenApiSpex.Plug.Cast` has changed (#39).
	To enable requests that contain a body as well as path or query params, the result of casting the
	request body is now placed in the `Conn.body_params` field, instead of the combined `Conn.params` field.

	This requires changing code such as Phoenix controller actions to from

	```elixir
	def create(conn, %UserRequest{user: %User{name: name, email: email}}) do
	```

	to

	```elixir
	def create(conn = %{body_params: %UserRequest{user: %User{name: name, email: email}}}, params) do
	```

	- Feature: A custom plug may be provided to render errors (#46)
	- Fix compiler warnings and improve CI process (#53)
	- Fix: Support casting GET requests without Content-Type header (#50, #49)
	- Open API Spex has been moved to the new `open-api-spex` Github organisation

	# 2.3.1

	- Docs: Update example application to include swagger generate mix task (#41)
	- Fix: Ignore charset in content-type header when looking up schema by content type. (#45)

	Thanks to [dmt](https://github.com/dmt) and [fenollp](https://github.com/fenollp) for contributions!

	# 2.3.0

	- Feature: Validate string enum types. (#33)
	- Feature: Detect and report missing API spec in `OpenApiSpex.Plug.Cast` (#37)
	- Fix: Correct atom for parameter `style` field typespec (#36)

	Thanks to [slavo2](https://github.com/slavo2) and [anagromataf](https://github.com/anagromataf) for
	contributions!

	# 2.2.0

	- Feature: Support composite schemas in `OpenApiSpex.schema`

	structs defined with `OpenApiSpex.schema` will include all properties defined in schemas
	listed in `allOf`. See the `OpenApiSpex.Schema` docs for some examples.

	- Feature: Support composite and polymorphic schemas with `OpenApiSpex.cast/3`.
	- `discriminator` is used to cast polymorphic shemas to a more specific schema.
	- `allOf` will cast all properties in each included schema
	- `oneOf` / `anyOf` will attempt to use each schema until a successful cast is made

	# 2.1.1

	- Fix: (#24, #25) Operations that define `parameters` and a `requestBody` schema can be validated.

	# 2.1.0

	- Feature: (#16) Error response from `OpenApiSpex.cast` when value contains unknown properties and schema declares `additionalProperties: false`.
	- Feature: (#20) Update swagger-ui to version 3.17.0.
	- Fix: (#17, #21, #22) Update typespecs for struct types.

	# 2.0.0

	Major version update following from API change in `OpenApiSpex.cast` and `OpenApiSpex.validate`.
	When casting/validating all parameters against an `OpenApiSpex.Operation`, the complete `Plug.Conn` struct must now be passed, where the combined params map was previously accepted.
	This allows `OpenApiSpex.cast` / `OpenApiSpex.validate` to check that the parameters are being supplied in the expected location (query, path, body, header, cookie).
	In version 2.0.0, only unexpected query parameters will cause a 422 response from `OpenApiSpex.Plug.Cast`, this may be extended in future versions to detect more invalid requests.

	Thanks [cstaud](https://github.com/cstaud), [rutho](https://github.com/ThomasRueckert), [anagromataf](https://github.com/anagromataf) for contributions!


	- Change: (#9) swagger-ui updated to 3.13.4
	- Change (#9) Unexpected query parameters will produce an error response from `OpenApiSpex.Plug.Cast`
	- Change: (#9) `OpenApiSpex.cast/4` now requires a complete `Plug.Conn` struct when casting all parameters of an `OpenApiSpex.Operation`
	- Change: (#14) `OpenApiSpex.validate/4` now requires a complete `Plug.Conn` struct when validating all parameters of an `OpenApiSpex.Operation`
	- Fix: (#11) Support resolving list of schema modules in `oneOf`, `anyOf`, etc.
	- Fix: `OpenApiSpex.schema` macro allows defining schemas without any properties
	- Fix: type declarations better reflect when `nil` is allowed


	# 1.1.4

	- `additionalProperties` is now `nil` by default, was previously `true`

	# 1.1.3

	- Fix several bugs and make some minor enhancements to schema casting and validating.
	- Add sample application to enable end-to-end testing

	# 1.1.2

	Fix openapi version output in generated spec.

	# 1.1.1

	Update swagger-ui to version 3.3.2

	# 1.1.0

	Include path to invalid element in validation errors.
	Eg: "#/user/name: Value does not match pattern: [a-zA-Z][a-zA-Z0-9_]+"

	# 1.0.1

	Cache API spec in application environment after first call to PutApiSpec plug

	# 1.0.0

	Initial release. This package is inspired by [phoenix_swagger](https://github.com/xerions/phoenix_swagger) but targets Open API Spec 3.0.


	diff --git a/README.md b/README.md
	index ac02c43..bab7e7b 100644
	--- a/README.md
	+++ b/README.md
	@@ -1,305 +1,305 @@
	# Open API Spex
	[![Build Status](https://travis-ci.com/open-api-spex/open_api_spex.svg?branch=master)](https://travis-ci.com/open-api-spex/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, "~> 3.3"}
	+ {:open_api_spex, "~> 3.4"}
	]
	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}
	@behaviour OpenApi

	@impl OpenApi
	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
	operation = String.to_existing_atom("#{action}_operation")
	apply(__MODULE__, operation, [])
	end

	@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 [Jason.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},
	birthday: %Schema{type: :string, description: "Birth date", format: :date},
	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()
	\|> Jason.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
	```

	## Validating and Casting Params

	Add the `OpenApiSpex.Plug.CastAndValidate` plug to a controller to validate request parameters, and to cast to Elixir types defined by the operation schema.

	```elixir
	plug OpenApiSpex.Plug.CastAndValidate, 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.CastAndValidate

	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: [
	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 = %{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
	```

	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:

	```json
	{
	"errors": [
	{
	"message": "Invalid format. Expected :date",
	"source": {
	"pointer": "/data/birthday"
	},
	"title": "Invalid value"
	}
	]
	}
	```

	See also `OpenApiSpex.cast_and_validate/3` and `OpenApiSpex.Cast.cast/3` for more examples 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/mix.exs b/mix.exs
	index 06d1d0d..35fb9b5 100644
	--- a/mix.exs
	+++ b/mix.exs
	@@ -1,64 +1,64 @@
	defmodule OpenApiSpex.Mixfile do
	use Mix.Project

	- @version "3.3.0"
	+ @version "3.4.0"

	def project do
	[
	app: :open_api_spex,
	version: @version,
	elixir: "~> 1.6",
	elixirc_paths: elixirc_paths(Mix.env()),
	start_permanent: Mix.env() == :prod,
	description: description(),
	package: package(),
	deps: deps(),
	consolidate_protocols: Mix.env() != :test,
	source_url: "https://github.com/open-api-spex/open_api_spex",
	homepage_url: "https://github.com/open-api-spex/open_api_spex",
	docs: [extras: ["README.md"], main: "readme", source_ref: "v#{@version}"],
	dialyzer: [
	plt_add_apps: [:mix, :jason, :poison],
	plt_add_deps: :apps_direct,
	flags: ["-Werror_handling", "-Wno_unused", "-Wunmatched_returns", "-Wunderspecs"],
	remove_defaults: [:unknown]
	]
	]
	end

	defp elixirc_paths(:test), do: ["lib", "test/support"]
	defp elixirc_paths(_), do: ["lib"]

	# Run "mix help compile.app" to learn about applications.
	def application, do: [extra_applications: []]

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

	defp package() do
	[
	name: "open_api_spex",
	files: ["lib", "mix.exs", "README.md", "LICENSE", "CHANGELOG.md"],
	maintainers: [
	"Mike Buhot (m.buhot@gmail.com)",
	"Moxley Stratton",
	"Pierre Fenoll (pierrefenoll@gmail.com)"
	],
	licenses: ["Mozilla Public License, version 2.0"],
	links: %{"GitHub" => "https://github.com/open-api-spex/open_api_spex"}
	]
	end

	# Run "mix help deps" to learn about dependencies.
	defp deps do
	[
	{:poison, "~> 3.1", optional: true},
	{:jason, "~> 1.0", optional: true},
	{:plug, "~> 1.7"},
	{:phoenix, "~> 1.3", only: :test},
	{:ex_doc, "~> 0.19", only: :dev, runtime: false},
	{:dialyxir, "~> 0.5", only: [:dev, :test], runtime: false}
	]
	end
	end

File Metadata

Mime Type: text/x-diff
Expires: Thu, Nov 28, 2:22 PM (1 d, 20 h)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 41048
Default Alt Text: (21 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions