Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/KittyHeaven/blue_bird
API Documentation Generator for the Phoenix Framework
https://github.com/KittyHeaven/blue_bird
api-blueprint api-documentation documentation-generator phoenix-framework
Last synced: about 1 month ago
JSON representation
API Documentation Generator for the Phoenix Framework
- Host: GitHub
- URL: https://github.com/KittyHeaven/blue_bird
- Owner: KittyHeaven
- License: mit
- Created: 2017-05-29T11:16:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2019-11-30T10:32:25.000Z (about 5 years ago)
- Last Synced: 2024-09-23T09:18:45.918Z (3 months ago)
- Topics: api-blueprint, api-documentation, documentation-generator, phoenix-framework
- Language: Elixir
- Homepage:
- Size: 313 KB
- Stars: 57
- Watchers: 5
- Forks: 13
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - 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. (Documentation)
- fucking-awesome-elixir - blue_bird - 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. (Documentation)
- awesome-elixir - blue_bird - 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. (Documentation)
README
# BlueBird
[](https://travis-ci.org/KittyHeaven/blue_bird)
[](https://hex.pm/packages/blue_bird)
[](https://coveralls.io/github/KittyHeaven/blue_bird?branch=master)
[](https://github.com/rhazdon/blue_bird/blob/master/LICENSE)
[](https://beta.hexfaktor.org/github/KittyHeaven/blue_bird)
`BlueBird` is an api documentation builder for the [Phoenix framework](http://www.phoenixframework.org/). The documentation is generated in the
[API Blueprint](https://apiblueprint.org/) format from annotations in
your controllers and from automated tests.
## Installation
1. Add BlueBird to your mix.exs dependencies:
```elixir
defp deps do
[{:blue_bird, "~> 0.4.0"}]
end
```
2. Run `mix deps.get` to fetch the dependencies:
```bash
$ mix deps.get
```
3. In `test/test_helper.exs`, start the BlueBird logger with `BlueBird.start()`
and configure ExUnit as follows:
```elixir
BlueBird.start()
ExUnit.start(formatters: [ExUnit.CLIFormatter, BlueBird.Formatter])
```
4. Add the following lines to `config.exs`:
```elixir
config :blue_bird,
docs_path: "priv/static/docs",
theme: "triple",
router: AppWeb.Router
```
5. Add `blue_bird_info` to your `mix.exs` to add global information:
```elixir
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:
```elixir
def controller do
quote do
...
use BlueBird.Controller
...
end
end
```
7. Install aglio:
```bash
$ npm install aglio -g
```
## Usage
### Router
By default, documentation is only generated for routes that use the `:api`
pipeline. You can configure which pipelines to use in the configuration.
```elixir
config :blue_bird,
pipelines: [:something_else]
```
### Controller
Use the `api/3` macro to annotate your controller functions.
```elixir
defmodule AppWeb.CommentController do
use AppWeb, :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
```
BlueBird groups routes by controller. By default, it uses the controller names
as group names in the headings. You can change the group name of a controller
by adding the `apigroup` macro to your controller modules. The macro can also
be used to add a group description.
```elixir
defmodule AppWeb.CommentController do
use AppWeb, :controller
apigroup "Blog Comments", "some description"
...
end
```
### Tests
In your tests, select which requests and responses you want to include in the
documentation by saving `conn` to `BlueBird.ConnLogger`:
```elixir
test "list comments for post", %{conn: conn} do
insert_posts_with_comments()
conn = conn
|> get(comments_path(conn, :index))
|> BlueBird.ConnLogger.save(title: "Without params")
assert json_response(conn, 200)
end
```
## Generating the documentation
First, run your tests:
```bash
$ mix test
```
All `conn`s that were saved to the `ConnLogger` will be processed. The
documentation will be written to the file `api.apib` in the directory specified
in the configuration. The file uses the [API Blueprint](https://apiblueprint.org) format.
There are [several tools](https://apiblueprint.org/tools.html#renderers) that
can render `apib` files to html. `BlueBird` has a mix task which uses
[Aglio renderer](https://github.com/danielgtaylor/aglio) to generate an html
document from the generated `apib` file.
```
$ 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`:
```elixir
config :blue_bird,
docs_path: "priv/static/docs",
theme: "triple",
router: YourAppWeb.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`: The [Aglio](https://github.com/danielgtaylor/aglio) theme to be used
for the html documentation.
- `router`: The router module of your application.
- `pipelines` (optional): Only routes that use the specified router pipelines
will be included in the documentation. Defaults to `[:api]` if not set.
- `ignore_headers` (optional): You can hide certain headers from the
documentation with this option. This can be helpful if you serve your
application behind a proxy. If the value is a list of strings as above, the
specified headers will be hidden from both requests and responses. If you
want to hide different headers from requests and responses, you can use a map
instead: `ignore_headers: %{request: ["ignore-me"], response: ["and-me"]}`.
- `trim_path` (optional): Allows you to remove a path prefix from the docs. For
example, if all your routes start with `/api` and you don't want to display
this prefix in the documentation, set `trim_path` to `"/api"`.
### `blue_bird_info()`
#### Options
- `host`: API host.
- `title`: Documentation title (can use Blueprint format).
- `description`: Documentation description (can use Blueprint format).
- `terms_of_service` (optional): Terms of service, string.
- `contact` (optional)
- `name` (optional)
- `url` (optional)
- `email` (optional)
- `license` (optional)
- `name` (optional)
- `url` (optional)
## 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 (or the pipelines you
configured in config.exs) will be added to the documentation.
### Body Parameters are not rendered
BlueBird reads the `body_params` from `%Plug.Conn{}`. This map is only set if
`body_params` is a binary.
#### Example
```elixir
post build_conn(), "/", Poison.encode! %{my: data} # recommended
post build_conn(), "/", "my=data"
```