PhoenixSwagger

PhoenixSwagger is the library that provides swagger integration to the phoenix web framework.

Installation

PhoenixSwagger provides phoenix.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.1.2"}]
end

Now you can use phoenix_swagger to generate swagger-ui file for you application.

Usage

You must provide swagger_spec/0 function in your Router.ex file. This function must return a map that contains the structure of a swagger object This defines the skeleton of your swagger spec, with the paths and definitions sections being filled in by phoenix_swagger.

def swagger_spec do
  %{
    swagger: "2.0",
    info: %{
      version: "0.0.1",
      title: "My awesome phoenix project."
    },
    securityDefinitions: %{
      basic_auth: %{
        type: "basic",
        description: "Standard HTTP basic authentication applies to all API operations."
      }
    },
    security: [
      %{basic_auth: []}
    ],
    tags: [
      %{
        name: "users",
        description: "Operations related to users"
      }
    ],
    consumes: [
      "application/vnd.api+json"
    ],
    produces: [
      "application/vnd.api+json"
    ],
    definitions: %{},
    paths: %{},
  }
end

PhoenixSwagger provides swagger_path/2 macro that generates swagger documentation for the certain phoenix controller.

Example:

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

The swagger_path macro takes two parameters:

The name of the controller action
do block containing calls into the PhoenixSwagger.Path module.

The body of the DSL is only a thin layer of syntax sugar over a regular phoenix function pipeline. The example above can be re-written as:

def swagger_path_index do
  import Phoenix.Swagger.Path
  get("/users")
  |> description("Short description")
  |> parameter(:query, :id, :integer, "Property id", required: true)
  |> response(200, "Description")
  |> nest
  |> to_json
end

The do bock always starts with one of the get, put, post, delete, head, options functions. This creates a new #SwaggerPath{} struct to pipeline through the remaining functions.

At a minimum, you should probably supply summary, description, parameter, and response docs.

The parameter provides description of the routing parameter for the given action and may take four positional parameters, and a keyword list of optional parameters:

The location of the parameter. Possible values are query, header, path, formData or body. [required];
The name of the parameter. [required];
The type of the parameter. Allowed only swagger data types [required];
Description of a parameter. Can be elixir's String or function/0 that returns elixir's string;
Keyword parameters can use any attribute from the swagger parameter spec, and additionally can use required: true to indicate that the parameter is mandatory.

Responses supply a status code, description and optional schema. The simplest way to supply a schema is to use the Schema.ref/1 helper function.

response 200, "Description", Schema.ref(:Post)

Schemas can be defined using the swagger_definitions macro. Helpers are included for defining JSON-API style resources:

swagger_definitions do
  JsonApi.resource(:User, :Users) do
    description "A user of the system."
    attributes do
      user_updated_at :string, "Last update timestamp UTC", format: "ISO-8601"
      user_created_at :string, "First created timestamp UTC"
      street_address :string, "Street address"
      email :string, "Email", required: true
    end
  end
end

This example adds 3 entries to the definitions section of the swagger document.

User: A JSON-API Response containing a single user
Users: for paginated responses with links to next, prev, first, last pages.
UserResource: The schema of the data object appearing in a User response, or each item of a Users response.

Each line in the attributes block should contain name, type, description, keyword-args. The keyword args can contain any Schema Object fields.

After this run the phoenix.swagger.generate mix task for the swagger-ui json file generation into directory with phoenix application:

mix phoenix.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 using -o or --output options:

mix phoenix.swagger.generate -o ~/my-phoenix-api.json

If you have more than one router in the project, then the -r or --router option can be used:

mix phoenix.swagger.generate -o ~/my-phoenix-api.json -r MyApp.Router

For more informantion, you can find swagger specification here.

matisojka/phoenix_swagger

PhoenixSwagger

Installation

Usage