phoenix_swagger v0.8.2 PhoenixSwagger View Source

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

Link to this section Summary

Functions

Use JSON library from phoenix configuration

Called when an application is started.

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.

Link to this section Functions

Use JSON library from phoenix configuration

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 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.

Link to this macro

swagger_path(action, list)

View Source (macro)

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 is any chain of functions with first argument being a PhoenixSwagger.Path.PathObject struct.

The verb and path can be set explicitly using the get, put, post, patch, delete functions, or inferred from the phoenix router automatically.

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
Link to this macro

swagger_schema(block)

View Source (macro)

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