BlueBird v0.3.2 BlueBird.Controller

Defines macros used to add documentation to api routes.

Usage

Use api/3 in your controllers. Optionally add the apigroup/1 or apigroup/2 macro to your controllers.

defmodule MyApp.Web.UserController do
  use BlueBird.Controller
  alias MyApp.Accounts

  apigroup "Customers", "These are the routes that we'll talk about."

  api :GET, "users" do
    title "List users"
    description "Lists all active users"
  end
  def index(conn, _params) do
    users = Accounts.list_users()
    render(conn, "index.html", users: users)
  end
end

Instead of adding use BlueBird.Controller to every controller module, you can also add it to the web.ex controller function to make it available in every controller.

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

Link to this section Summary

Functions

Describes a route

Defines the name and an optional description for a resource group

Link to this section Functions

Link to this macro api(method, path, list) (macro)

Describes a route.

api <method> <url> do ... end
  • method: HTTP method (GET, POST, PUT etc.)
  • url: Route as defined in the Phoenix router
  • title (optional): Title for the action
  • description (optional): Description of the route
  • note (optional): Note
  • warning (optional): Warning
  • parameter (optional): Used for path and query parameters. It takes the name as defined in the route and the type. The third parameter is an optional keyword list with additional options. See BlueBird.Parameter for descriptions of the available options.

Example

api :GET, "user/:id/posts/:slug" do
  title "Show post"
  description "Show post by user ID and post slug"
  note "You should really know this."
  warning "Please don't ever do this."
  parameter :id, :integer
  parameter :slug, :string, [
    description: "This is the post slug.",
    example: "whatever"
  ]
Link to this macro apigroup(name, description \\ "") (macro)

Defines the name and an optional description for a resource group.

BlueBird defines groups by the controller. By default, the group name is taken from the controller name. If you want to specify a different name, you can use this macro. You can also add a group description as a second parameter.

Example

apigroup "resource group name"

or

apigroup "resource group name", "description"