PhoenixSwagger
is the library that provides swagger integration
to the phoenix web framework.
The PhoenixSwagger
generates Swagger
specification for Phoenix
controllers and
validates the requests.
PhoenixSwagger
provides phx.swagger.generate
mix task for the swagger-ui json
file generation that contains swagger specification that describes API of the phoenix
application.
You just need to add the swagger DSL to your controllers and then run this one mix task to generate the json files.
To use PhoenixSwagger
with a phoenix application just add it to your list of
dependencies in the mix.exs
file:
def deps do
[
{:phoenix_swagger, "~> 0.6.1"},
{:ex_json_schema, "~> 0.5"} # optional
]
end
For Phoenix 1.2 or lower, please use version "~> 0.5.0"
.
ex_json_schema
is an optional dependency of phoenix_swagger
required only for schema validation plug and test helper.
Now you can use phoenix_swagger
to generate swagger-ui
file for you application.
The outline of the swagger document should be returned from a swagger_info/0
function
defined in your phoenix Router.ex
module.
defmodule MyApp.Router do
use MyApp.Web, :router
pipeline :api do
plug :accepts, ["json"]
end
scope "/api", MyApp do
pipe_through :api
resources "/users", UserController
end
def swagger_info do
%{
info: %{
version: "1.0",
title: "My App"
}
}
end
end
The version
and title
are mandatory fields. By default the version
will be 0.0.1
and the title
will be <enter your title>
if you do not provide swagger_info/0
function.
See the swaggerObject specification for details of other information that can be included.
PhoenixSwagger
provides swagger_path/2
macro that generates swagger specification
for the certain phoenix controller action.
Example:
use PhoenixSwagger
swagger_path :index do
get "/posts"
description "List blog posts"
responses 200, "Success"
end
def index(conn, _params) do
posts = Repo.all(Post)
render(conn, "index.json", posts: posts)
end
The swagger_path
macro takes two parameters:
- Name of controller action;
do
block that contains theswagger
specification for the controller action.
Within the do-end block, the DSL provided by the PhoenixSwagger.Path
module can be used.
The DSL always starts with one of the get
, put
, post
, delete
, head
, options
functions,
followed by any functions with first argument being a PhoenixSwagger.Path.PathObject
struct.
Example:
swagger_path :index do
get "/api/v1/{org_id}/users"
summary "Query for users"
description "Query for users. This operation supports with paging and filtering"
produces "application/json"
tag "Users"
operation_id "list_users"
paging
parameters do
org_id :path, :string, "Organization ID", required: true
zipcode :query, :string, "Address Zip Code", required: true, example: "90210"
include :query, :array, "Related resources to include in response",
items: [type: :string, enum: [:organisation, :favourites, :purchases]],
collectionFormat: :csv
end
response 200, "OK", Schema.ref(:Users)
response 400, "Client Error"
end
Response schema definitions are placed in a swagger_definitions/0
function within each controller module.
This function should return a map in the format of a swagger definitionsObject.
The swagger_schema/2
macro can be used to build a schema definition using the functions provided by the PhoenixSwagger.Schema
module.
Example:
def swagger_definitions do
%{
User: swagger_schema do
title "User"
description "A user of the application"
properties do
name :string, "Users name", required: true
id :string, "Unique identifier", required: true
address :string, "Home address"
preferences (Schema.new do
properties do
subscribe_to_mailing_list :boolean, "mailing list subscription", default: true
send_special_offers :boolean, "special offers list subscription", default: true
end
end)
end
example %{
name: "Joe",
id: "123",
address: "742 Evergreen Terrace"
}
end,
Users: swagger_schema do
title "Users"
description "A collection of Users"
type :array
items Schema.ref(:User)
end
}
end
The PhoenixSwagger.JsonApi
module provides helpers for constructing JSON:API schemas easily.
PhoenixSwagger.JsonApi.resource/1
describes a JSON:API resource object.
PhoenixSwagger.JsonApi.page/1
and PhoenixSwagger.JsonApi.single/1
can then be used to wrap a resource in a JSON:API top level object
Example:
use PhoenixSwagger
def swagger_definitions do
%{
UserResource: JsonApi.resource do
description "A user that may have one or more supporter pages."
attributes do
phone :string, "Users phone number"
full_name :string, "Full name"
user_updated_at :string, "Last update timestamp UTC", format: "ISO-8601"
user_created_at :string, "First created timestamp UTC"
email :string, "Email", required: true
birthday :string, "Birthday in YYYY-MM-DD format"
address Schema.ref(:Address), "Users address"
end
link :self, "The link to this user resource"
relationship :posts
end,
Users: JsonApi.page(:UserResource),
User: JsonApi.single(:UserResource)
}
end
swagger_path :index do
get "/api/v1/users"
paging size: "page[size]", number: "page[number]"
response 200, "OK", Schema.ref(:Users)
end
After adding swagger spec to you controllers, run the phx.swagger.generate
mix task for the swagger-ui
json file generation into directory with phoenix
application:
mix phx.swagger.generate
As the result there will be swagger.json
file into root directory of the phoenix
application.
To generate swagger
file with the custom name/place, pass it to the main mix task:
mix phx.swagger.generate ~/my-phoenix-api.json
If the project contains multiple Router
modules, you can generate a swagger file for each one by specifying the router module as an argument to mix phx.swagger.generate
:
mix phx.swagger.generate booking-api.json -r MyApp.BookingRouter
mix phx.swagger.generate reports-api.json -r MyApp.ReportsRouter
mix phx.swagger.generate admin-api.json -r MyApp.AdminRouter
For more informantion, you can find swagger
specification here.
Besides generator of swagger
schemas, the phoenix_swagger
provides validator of input parameters of resources.
Suppose you have following resource in your schema:
...
...
"/history": {
"get": {
"parameters": [
{
"name": "offset",
"in": "query",
"type": "integer",
"format": "int32",
"description": "Offset the list of returned results by this amount. Default is zero."
},
{
"name": "limit",
"in": "query",
"type": "integer",
"format": "int32",
"description": "Integer of items to retrieve. Default is 5, maximum is 100."
}]
}
}
...
...
The phoenix_swagger
provides PhoenixSwagger.Validator.parse_swagger_schema/1
API to load a swagger schema by
the given path or list of paths. This API should be called during application startup to parse/load a swagger schema.
After this, the PhoenixSwagger.Validator.validate/2
can be used to validate resources.
For example:
iex(1)> Validator.validate("/history", %{"limit" => "10"})
{:error,"Type mismatch. Expected Integer but got String.", "#/limit"}
iex(2)> Validator.validate("/history", %{"limit" => 10, "offset" => 100})
:ok
Besides validate/2
API, the phoenix_swagger
validator can be used via Plug to validate
intput parameters of your controllers.
Just add PhoenixSwagger.Plug.Validate
plug to your router:
pipeline :api do
plug :accepts, ["json"]
plug PhoenixSwagger.Plug.Validate
end
scope "/api", MyApp do
pipe_through :api
post "/users", UsersController, :send
end
The current minimal version of elixir should be 1.3
and in this case you must add phoenix_swagger
application
to the application list in your mix.exs
.
PhoenixSwagger also includes a testing helper module PhoenixSwagger.SchemaTest
to conveniently assert that responses
from Phoenix controller actions conform to your swagger schema.
In your controller test files add the PhoenixSwagger.SchemaTest
mixin with the path to your swagger spec:
defmodule YourApp.UserControllerTest do
use YourApp.ConnCase, async: true
use PhoenixSwagger.SchemaTest, "priv/static/swagger.json"
Then in each test, the context will contain the swagger_schema, which can be used with
the validate_resp_schema
function:
test "shows chosen resource", %{conn: conn, swagger_schema: schema} do
user = Repo.insert! struct(User, @valid_attrs)
response =
conn
|> get(user_path(conn, :show, user))
|> validate_resp_schema(schema, "UserResponse")
|> json_response(200)
end
PhoenixSwagger includes a plug with all static assets required to host swagger-ui from your Phoenix application.
Usage:
Generate a swagger file and place it in your applications priv/static
dir:
mix phx.swagger.generate priv/static/myapp.json
Add a swagger scope to your router, and forward all requests to SwaggerUI
scope "/api/swagger" do
forward "/", PhoenixSwagger.Plug.SwaggerUI, otp_app: :myapp, swagger_file: "swagger.json"
end
Run the server with mix phoenix.server
and browse to localhost:4000/api/swagger
,
Swagger-ui should be shown with your swagger spec loaded.
See the examples/simple
project for a runnable example with swagger-ui.