BlueBird v0.4.0 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
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 routertitle
(optional): Title for the actiondescription
(optional): Description of the routenote
(optional): Notewarning
(optional): Warningparameter
(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. SeeBlueBird.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"
]
end
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"