phoenix_swagger v0.7.0 PhoenixSwagger
The PhoenixSwagger module provides macros for defining swagger operations and schemas.
Example:
use PhoenixSwagger
swagger_path :create do
post "/api/v1/{team}/users"
summary "Create a new user"
consumes "application/json"
produces "application/json"
parameters do
user :body, Schema.ref(:User), "user attributes"
team :path, :string, "Users team ID"
end
response 200, "OK", Schema.ref(:User)
end
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 adress"
end
end
}
end
Summary
Functions
Called when an application is started
Macros
Swagger operations (aka “paths”) are defined inside a swagger_path
block
Builds a swagger schema map using a DSL from the functions defined in PhoenixSwagger.Schema
Functions
Called when an application is started.
This function is called when an application is started using
Application.start/2
(and functions on top of that, such as
Application.ensure_started/2
). This function should start the top-level
process of the application (which should be the top supervisor of the
application’s supervision tree if the application follows the OTP design
principles around supervision).
start_type
defines how the application is started:
:normal
- used if the startup is a normal startup or if the application is distributed and is started on the current node because of a failover from another node and the application specification key:start_phases
is:undefined
.{:takeover, node}
- used if the application is distributed and is started on the current node because of a failover on the nodenode
.{:failover, node}
- used if the application is distributed and is started on the current node because of a failover on nodenode
, and the application specification key:start_phases
is not:undefined
.
start_args
are the arguments passed to the application in the :mod
specification key (e.g., mod: {MyApp, [:my_args]}
).
This function should either return {:ok, pid}
or {:ok, pid, state}
if
startup is successful. pid
should be the PID of the top supervisor. state
can be an arbitrary term, and if omitted will default to []
; if the
application is later stopped, state
is passed to the stop/1
callback (see
the documentation for the c:stop/1
callback for more information).
use Application
provides no default implementation for the start/2
callback.
Callback implementation for Application.start/2
.
Macros
Swagger operations (aka “paths”) are defined inside a swagger_path
block.
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.
Swagger tags
will default to match the module name with trailing Controller
removed.
Eg operations defined in module MyApp.UserController will have tags: ["User"]
.
Swagger operationId
will default to the fully qualified action function name.
Eg index
action in MyApp.UserController
will have operationId: "MyApp.UserController.index"
.
Example
defmodule ExampleController do
use ExampleApp.Web, :controller
use PhoenixSwagger
swagger_path :index do
get "/users"
summary "Get users"
description "Get users, filtering by account ID"
parameter :query, :id, :integer, "account id", required: true
response 200, "Description", :Users
tag "users"
end
def index(conn, _params) do
posts = Repo.all(Post)
render(conn, "index.json", posts: posts)
end
end
Builds a swagger schema map using a DSL from the functions defined in PhoenixSwagger.Schema
.
Example
iex> use PhoenixSwagger
...> swagger_schema do
...> title "Pet"
...> description "A pet in the pet store"
...> properties do
...> id :integer, "Unique identifier", required: true, format: :int64
...> name :string, "Pets name", required: true
...> tags array(:string), "Tag categories for this pet"
...> end
...> additional_properties false
...> end
%{
"title" => "Pet",
"type" => "object",
"description" => "A pet in the pet store",
"properties" => %{
"id" => %{
"description" => "Unique identifier",
"format" => "int64",
"type" => "integer"
},
"name" => %{
"description" => "Pets name",
"type" => "string"
},
"tags" => %{
"description" => "Tag categories for this pet",
"items" => %{
"type" => "string"
},
"type" => "array"
}
},
"required" => ["name", "id"],
"additionalProperties" => false
}
iex> use PhoenixSwagger
...> swagger_schema do
...> title "Phone"
...> description "An 8 digit phone number with optional 2 digit area code"
...> type :string
...> max_length 11
...> pattern ~S"^(([0-9]{2}))?[0-9]{4}-[0-9]{4}$"
...> end
%{
"description" => "An 8 digit phone number with optional 2 digit area code",
"maxLength" => 11,
"pattern" => "^(\([0-9]{2}\))?[0-9]{4}-[0-9]{4}$",
"title" => "Phone",
"type" => "string"
}