Leverage Open API Specification 3 (formerly 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 SwaggerUI
Full documentation available on HexDocs.
The package can be installed by adding :open_api_spex to your list of dependencies in mix.exs:
def deps do
[
{:open_api_spex, "~> 3.13"}
]
endStart by adding an ApiSpec module to your application to populate an OpenApiSpex.OpenApi struct.
defmodule MyAppWeb.ApiSpec do
alias OpenApiSpex.{Components, Info, OpenApi, Paths, Server}
alias MyAppWeb.{Endpoint, Router}
@behaviour OpenApi
@impl OpenApi
def spec do
%OpenApi{
servers: [
# Populate the Server info from a phoenix endpoint
Server.from_endpoint(Endpoint)
],
info: %Info{
title: "My App",
version: "1.0"
},
# Populate the paths from a phoenix router
paths: Paths.from_router(Router)
}
|> OpenApiSpex.resolve_schema_modules() # Discover request/response schemas from path specs
end
endOr you can use your application's spec values in the info: key.
info: %Info{
title: to_string(Application.spec(:my_app, :description)),
version: to_string(Application.spec(:my_app, :vsn))
}In case your API requires authorization you can add security schemes as part of the components in the main spec.
components: %Components{
securitySchemes: %{"authorization" => %SecurityScheme{type: "http", scheme: "bearer"}}
}Once the security scheme is defined you can declare it. Please note that the key below matches the one defined in the security scheme, in the our example, "authorization".
security: [%{"authorization" => []}]If you require authorization for all endpoints you can declare the security in the main spec. In case you need authorization only for specific endpoints, or if you are using more than one security scheme, you can declare it as part of each operation.
To learn more about the different security schemes please the check the official documentation.
For each plug (controller) that will handle API requests, operations need to be defined that the plug/controller will handle.
defmodule MyAppWeb.UserController do
use MyAppWeb, :controller
use OpenApiSpex.ControllerSpecs
alias MyAppWeb.Schemas.{UserParams, UserResponse}
tags ["users"]
security [%{}, %{"petstore_auth" => ["write:users", "read:users"]}]
operation :update,
summary: "Update user",
parameters: [
id: [in: :path, description: "User ID", type: :integer, example: 1001]
],
request_body: {"User params", "application/json", UserParams},
responses: [
ok: {"User response", "application/json", UserResponse}
]
def update(conn, %{"id" => id}) do
json(conn, %{
data: %{
id: id,
name: "joe user",
email: "joe@gmail.com"
}
})
end
endNote: In order to prevent Elixir Formatter from automatically adding parentheses to the ControllerSpecs macro
call arguments, add :open_api_spex to the import_deps list in .formatter.exs:
.formatter.exs:
[
import_deps: [:open_api_spex]
]For further information about defining operations, see OpenApiSpex.ControllerSpecs.
If you need to omit the spec for some action then pass false to the
second argument of operation/2 for the action:
operation :create, falseEach definition in a controller action or plug operation is converted
to an %OpenApiSpex.Operation{} struct. The definitions are read
by your application's ApiSpec module, which in turn is
called from the OpenApiSpex.Plug.PutApiSpex plug on each request.
The definitions data is cached, so it does not actually extract the definitions on each request.
Note that the names of the OpenAPI fields follow snake_case naming convention instead of
OpenAPI's (and JSON Schema's) camelCase convention.
If ControllerSpecs-style operation specs don't provide the flexibility you need, the %Operation{} struct
and related structs can be used instead. See the
example user controller that uses %Operation{} structs.
For examples of other action operations, see the example web app.
Next, declare JSON schema modules for the request and response bodies.
In each schema module, call OpenApiSpex.schema/1, passing the schema definition. The schema must
have keys described in OpenApiSpex.Schema.t. This will define a %OpenApiSpex.Schema{} struct.
This struct is made available from the schema/0 public function, which is generated by OpenApiSpex.schema/1.
You may optionally have the data described by the schema turned into a struct linked to the JSON schema by adding "x-struct": __MODULE__
to the schema.
defmodule MyAppWeb.Schemas do
alias OpenApiSpex.Schema
defmodule User do
require OpenApiSpex
OpenApiSpex.schema(%{
# The title is optional. It defaults to the last section of the module name.
# So the derived title for MyApp.User is "User".
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},
birthday: %Schema{type: :string, description: "Birth date", format: :date},
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",
"birthday" => "1970-01-01T12:34:55Z",
"inserted_at" => "2017-09-12T12:34:55Z",
"updated_at" => "2017-09-13T10:11:12Z"
}
})
end
defmodule UserResponse do
require OpenApiSpex
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",
"birthday" => "1970-01-01T12:34:55Z",
"inserted_at" => "2017-09-12T12:34:55Z",
"updated_at" => "2017-09-13T10:11:12Z"
}
}
})
end
endFor more examples of schema definitions, see the sample Phoenix app.
To serve the API spec from your application, first add the OpenApiSpex.Plug.PutApiSpec plug somewhere in the pipeline.
pipeline :api do
plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec
endNow the spec will be available for use in downstream plugs.
The OpenApiSpex.Plug.RenderSpec plug will render the spec as JSON:
scope "/api" do
pipe_through :api
resources "/users", MyAppWeb.UserController, only: [:create, :index, :show]
get "/openapi", OpenApiSpex.Plug.RenderSpec, []
endNote that the above snippet uses scope/3. Some Phoenix projects will instead use scope/4 which adds an alias to all modules declared in the scope, as shown below:
scope "/api", MyAppWeb do
pipe_through :api
# Note the lack of `MyAppWeb` below for `UserController`, because the alias is now implicit
resources "/users", UserController, only: [:create, :index, :show]
# However, the alias now applies to `RenderSpec` as well, which will cause errors
get "/openapi", OpenApiSpex.Plug.RenderSpec, []
endIn this case, the RenderSpec module will be aliased as MyAppWeb.OpenApiSpex.Plug.RenderSpec, which will cause linter errors and fail at runtime. In order to prevent this, remove the alias from the scope invocation (MyAppWeb) and fully qualify the other controllers/functions (e.g. MyAppWeb.UserController instead of just UserController)
In development, to ensure the rendered spec is refreshed, you should disable caching with:
# config/dev.exs
config :open_api_spex, :cache_adapter, OpenApiSpex.Plug.NoneCacheYou can write the swagger file to disk using the following Mix task and optionally, for your convenience, create a direct alias:
mix openapi.spec.json --spec MyAppWeb.ApiSpec
mix openapi.spec.yaml --spec MyAppWeb.ApiSpecInvoking this task starts the application by default. This can be
disabled with the --start-app=false option.
Please make to replace any calls to OpenApiSpex.Server.from_endpoint with a %OpenApiSpex.Server{} struct like below:
%OpenApi{
info: %Info{
title: "Phoenix App",
version: "1.0"
},
# Replace this 👇
servers: [OpenApiSpex.Server.from_endpoint(MyAppWeb.Endpoint)],
# With this 👇
servers: [%OpenApiSpex.Server{url: "https://yourapi.example.com"}],
}NOTE: You need to add the ymlr dependency to write swagger file in YAML format:
def deps do
[
{:ymlr, "~> 2.0"}
]
endFor more options read the docs.
mix help openapi.spec.json
mix help openapi.spec.yamlOnce your API spec is available through a route (see "Serve the Spec"), 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.
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
⚠️ This functionality currently converts Strings into Atoms, which makes it potentially vulnerable to DoS attacks. 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:
# 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!()
|> List.first()
|> OpenApiSpex.OpenApi.Decode.decode()You can then use the loaded spec to with OpenApiSpex.cast_and_validate/3, like:
{:ok, _} = OpenApiSpex.cast_and_validate(
open_api_spec_from_json, # or open_api_spec_from_yaml
spec.paths["/some_path"].post,
test_conn
)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.
See OpenApiSpex.cast_value/3 for the latter.
The rest of this section describes implicit casting and validating the request before it reaches your controller action.
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.
# Phoenix
plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true
# Plug
plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true, operation_id: "UserController.create"The json_render_error_v2: true is a work-around for a bug in the format of the default error renderer.
It will be not needed in version 4.0.
For Phoenix apps, the operation_id can be inferred from the contents of conn.private.
The data shape of the default error renderer follows the JSON:API spec for error responses. For
convenience, the OpenApiSpex.JsonErrorResponse schema module is available that specifies
the shape, and it can be used in your API specs.
Example usage of CastAndValidate in a Phoenix controller:
defmodule MyAppWeb.UserController do
use MyAppWeb, :controller
use OpenApiSpex.ControllerSpecs
alias MyAppWeb.Schemas.{UserParams, UserResponse}
plug OpenApiSpex.Plug.CastAndValidate, json_render_error_v2: true
operation :update,
summary: "Update user",
description: "Updates with the given params.\nThis is another line of text in the description.",
parameters: [
id: [in: :path, type: :integer, description: "user ID"],
vsn: [in: :query, type: :integer, description: "API version number"],
"api-version": [in: :header, type: :integer, description: "API version number"]
],
request_body: {"The user attributes", "application/json", UserParams},
responses: %{
201 => {"User", "application/json", UserResponse},
422 => OpenApiSpex.JsonErrorResponse.response()
}
def update(
conn = %{
body_params: %UserParams{
name: name,
email: email,
birthday: %Date{} = birthday
}
},
%{id: id}
) do
# conn.body_params cast to UserRequest struct
# conn.params combines path params, query params and header params
# conn.params.id cast to integer
# conn.params.vsn cast to integer
# conn.params[:"api-version"] cast to integer
# params is the same as conn.params
# params.id cast to integer
# Note: Using pattern-matching in the action function's arguments can
# cause Dialyzer to complain. This is because Dialyzer expects the
# `conn` and `params` arguments to have string keys, not atom keys.
# To resolve this, fetch the `:body_params` with
# `body_params = Map.get(conn, :body_params)`.
end
endNow 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:
{
"errors": [
{
"detail": "Invalid format. Expected :date",
"source": {
"pointer": "/data/birthday"
},
"title": "Invalid value"
}
]
}If you would like a different response JSON shape, create a plug module to shape the response,
and pass it to CastAndValidate:
plug OpenApiSpex.Plug.CastAndValidate, render_error: MyErrorRendererPlugdefmodule MyErrorRendererPlug do
@behaviour Plug
alias Plug.Conn
alias OpenApiSpex.OpenApi
@impl Plug
def init(errors), do: errors
@impl Plug
def call(conn, errors) when is_list(errors) do
response = %{
errors: Enum.map(errors, &to_string/1)
}
json = OpenApi.json_encoder().encode!(response)
conn
|> Conn.put_resp_content_type("application/json")
|> Conn.send_resp(422, json)
end
endOpenApiSpex can generate example data from specs. This has a similar result as SwaggerUI when it generates example requests or responses for an endpoint. This is a convenient way to generate test data for controller/plug tests.
use MyAppWeb.ConnCase
test "create/2", %{conn: conn} do
request_body = OpenApiSpex.Schema.example(MyAppWeb.Schemas.UserRequest.schema())
json =
conn
|> post(user_path(conn), request_body)
|> json_response(200)
endAs schemas evolve, you may want to confirm that the examples given match the schemas.
Use the OpenApiSpex.TestAssertions module to assert on schema validations.
use ExUnit.Case
import OpenApiSpex.TestAssertions
test "UsersResponse example matches schema" do
api_spec = MyAppWeb.ApiSpec.spec()
schema = MyAppWeb.Schemas.UsersResponse.schema()
assert_schema(schema.example, "UsersResponse", api_spec)
endAPI responses can be tested against schemas using OpenApiSpex.TestAssertions also:
use MyAppWeb.ConnCase
import OpenApiSpex.TestAssertions
test "UserController produces a UsersResponse", %{conn: conn} do
json =
conn
|> get(user_path(conn, :index))
|> json_response(200)
api_spec = MyAppWeb.ApiSpec.spec()
assert_schema(json, "UsersResponse", api_spec)
endCopyright (c) 2017 Michael Buhot
Licensed under the Mozilla Public License, Version 2.0, which can be found in LICENSE.