warning: OpenApiSpex.Test.Assertions.assert_schema/3 is deprecated. Use OpenApiSpex.TestAssertions.assert_schema/3 instead
test/my_controller_test.exs:21
```
New API:
```elixir
defmodule MyAppWeb.MyControllerTest do
use MyApp.ConnCase
# New module
import OpenApiSpex.TestAssertions
# The test themselves don't need to change,
# but the new assertion is more discerning,
# so it may find problems that the old API didn't.
end
```
# 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)
- 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/CONTRIBUTING.md b/CONTRIBUTING.md
index 0710f07..7f3327b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,39 +1,39 @@
# Contributing
## Open an issue
If you've found a bug or would like to discuss a new feature, start by [opening an issue](https://github.com/open-api-spex/open_api_spex/issues/new).
Where possible, please refer to the relevant sections of the Open API Specification 3.0 or JSON Schema Specification:
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.
> :warning: This functionality currently converts Strings into Atoms, which makes it potentially [vulnerable to DoS attacks](https://til.hashrocket.com/posts/gkwwfy9xvw-converting-strings-to-atoms-safely). We recommend that you load Open API Schemas from *known files* during application startup and *not dynamically from external sources at runtime*.
OpenApiSpex has functionality to import an existing schema, casting it into an %OpenApi{} struct. This means you can load a schema that is JSON or YAML encoded. See the example below:
```elixir
# Importing an existing JSON encoded schema
open_api_spec_from_json = "encoded_schema.json"
|> File.read!()
|> Jason.decode!()
|> OpenApiSpex.OpenApi.Decode.decode()
# Importing an existing YAML encoded schema
open_api_spec_from_yaml = "encoded_schema.yaml"
|> YamlElixir.read_all_from_file!()
|> OpenApiSpex.OpenApi.Decode.decode()
```
You can then use the loaded spec to with `OpenApiSpex.cast_and_validate/4`, like:
```elixir
{:ok, _} = OpenApiSpex.cast_and_validate(
open_api_spec_from_json, # or open_api_spec_from_yaml
spec.paths["/some_path"].post,
test_conn,
"application/json"
)
```
## Validating and Casting Params
OpenApiSpex can automatically validate requests before they reach the controller action function. Or if you prefer,
you can explicitly call on OpenApiSpex to cast and validate the params within the controller action. This section
describes the former.
First, the `plug OpenApiSpex.Plug.PutApiSpec` needs to be called in the Router, as described above.
Add the `OpenApiSpex.Plug.CastAndValidate` plug to a controller to validate request parameters and to cast to Elixir types defined by the operation schema.