BlueBird

BlueBird is a library written in the Elixir programming language for the Phoenix framework. It lets you generate API documentation in the API Blueprint format from annotations in controllers and automated tests.

Installation

1. Add BlueBird to your mix.exs dependencies:

defp deps do
  [{:blue_bird, "~> 0.3.4"}]
end

2. Run mix deps.get to fetch the dependencies:

$ mix deps.get

3. In test/test_helper.exs, start the BlueBird logger with BlueBird.start() and configure the results formatter as follows:

BlueBird.start()
ExUnit.start(formatters: [ExUnit.CLIFormatter, BlueBird.Formatter])

4. Add the following lines to config.exs:

config :blue_bird,
  docs_path: "priv/static/docs",
  theme: "triple",
  router: MyApp.Web.Router

5. Add blue_bird_info to your mix.exs to improve the generated docs:

def blue_bird_info do
  [
    host: "https://api.acme.com",
    title: "ACME API",
    description: """
                 API requires authorization. All requests must have valid
                 `auth_token`.
                 """
  ]
end

6. Add BlueBird.Controller to your web.ex controller function:

def controller do
  quote do
    ...
    use BlueBird.Controller
    ...
  end
end

7. Install aglio:

$ npm install aglio -g

Usage

Controller

Use the api\3 macro to generate the specification for the controller action.

defmodule App.CommentController do
  use App.Web, :controller

  api :GET, "/posts/:post_id/comments" do
    title "List comments"
    description "Optional description"
    note "Optional note"
    warning "Optional warning"
    parameter :post_id, :integer, [description: "Post ID or slug"]
  end
  def index(conn, %{"post_id" => post_id}) do
    ...
  end
end

Optionally use the apigroup macro to set the resource group name and description.

defmodule App.CommentController do
  use App.Web, :controller

  apigroup "Blog Comments", "some description"
  ...
end

Router

Currently, BlueBird expects that the routes are piped through :api.

defmodule TestRouter do
  use Phoenix.Router
  import Plug.Conn
  import Phoenix.Controller

  pipeline :api do
    ...
  end

  pipeline :foo do
    ...
  end

  scope "/" do
    pipe_through :api
    get "/get", TestController, :get  # This will work
  end

  scope "/" do
    pipe_through [:api, :foo]
    get "/get", TestController, :get  # This will work
  end

  scope "/" do
    pipe_through :foo
    get "/get", TestController, :get  # This will not work
  end
end

Tests

In your tests, select which requests and responses you want to include in the documentation by saving conn to BlueBird.ConnLogger:

test "list comments for post", %{conn: conn} do
  insert_posts_with_comments()

  conn = conn
  |> get(comments_path(conn, :index)
  |> BlueBird.ConnLogger.save()

  assert json_response(conn, 200)
end

After you run your tests, documentation will be written to api.apib in the API Blueprint format.

$ mix test

To generate an HTML documentation, use the convenience wrapper to the Aglio renderer.

$ mix bird.gen.docs

If you use BlueBird in an umbrella app, you must run the command from within the folder of the child app (e.g. apps/myapp_web).

Configuration

config.exs:

The configuration options can be setup in config.exs:

config :blue_bird,
  docs_path: "priv/static/docs",
  theme: "triple",
  router: YourApp.Web.Router,
  pipelines: [:api],
  ignore_headers: ["not-wanted"]

Options

• docs_path: Specify the path where the documentation will be generated. If you want to serve the documentation directly from the phoenix app, you can specify priv/static/docs. If you use BlueBird within an umbrella app, the path is relative to the root folder of the umbrella app.
• theme: HTML theme is generated using the Aglio renderer.
• router: Router of your application, in Phoenix 1.3 it will be YourAppName.Web.Router.
• ignore_headers (optional): If you want certain headers to be hidden from the documentation, you can add a list of header keys here. This can be helpful if you serve your application behind a proxy.
• pipelines (optional): Only routes that use the specified router pipelines will be included in the documentation. Defaults to [:api] if not set.

blue_bird_info():

Options:

• host: API host.
• title: Documentation title (can use Blueprint format).
• description: Documentation description (can use Blueprint format).

FAQ

Route is not generated after adding API annotations to the controller

Please make sure that the route you are using in the annotation matches the route from the phoenix router (including params) exactly. Run mix phoenix.routes (or mix phx.routes if Phoenix >= 1.3) and compare the routes.

Also note that only routes that use the api pipeline will be added to the documentation.

Body Parameter are not rendered

BlueBird reads the body_params from %Plug.Conn{}. These map is only set if body_params is a binary.

Example

post build_conn(), "/", Poison.encode! %{my: data}  # recommended
post build_conn(), "/", "my=data"