PhoenixSwagger (phoenix_swagger v0.8.3) 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

json_library()

Use JSON library from phoenix configuration

start(type, args)

Callback implementation for Application.start/2.

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.

Link to this section Functions

json_library()

Use JSON library from phoenix configuration

start(type, args)

Callback implementation for Application.start/2.

swagger_path(action, list)

(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

swagger_schema(block)

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