phoenix_swagger v0.6.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

start(type, args)

Called when an application is started

Macros

swagger_path(action, list)

Swagger operations (aka “paths”) are defined inside a swagger_path block

swagger_schema(block)

Builds a swagger schema map using a DSL from the functions defined in PhoenixSwagger.Schema

Functions

start(type, args)

Called when an application is started.

This function is called when an the 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 mode 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 node node.
{:failover, node} - used if the application is distributed and is started on the current node because of a failover on node node, 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_path(action, list)

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

swagger_schema(block)

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"
}