{"id":13507811,"url":"https://github.com/rhazdon/blue_bird","last_synced_at":"2025-12-12T00:23:29.178Z","repository":{"id":57480036,"uuid":"92732764","full_name":"rhazdon/blue_bird","owner":"rhazdon","description":"API Documentation Generator for the Phoenix Framework","archived":true,"fork":false,"pushed_at":"2019-11-30T10:32:25.000Z","size":320,"stargazers_count":58,"open_issues_count":9,"forks_count":13,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-02T23:35:11.945Z","etag":null,"topics":["api-blueprint","api-documentation","documentation-generator","phoenix-framework"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhazdon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-29T11:16:15.000Z","updated_at":"2025-01-16T11:30:17.000Z","dependencies_parsed_at":"2022-09-17T05:23:37.259Z","dependency_job_id":null,"html_url":"https://github.com/rhazdon/blue_bird","commit_stats":null,"previous_names":["kittyheaven/blue_bird"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhazdon%2Fblue_bird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhazdon%2Fblue_bird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhazdon%2Fblue_bird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhazdon%2Fblue_bird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhazdon","download_url":"https://codeload.github.com/rhazdon/blue_bird/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246301963,"owners_count":20755512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-blueprint","api-documentation","documentation-generator","phoenix-framework"],"created_at":"2024-08-01T02:00:39.740Z","updated_at":"2025-10-21T18:49:06.125Z","avatar_url":"https://github.com/rhazdon.png","language":"Elixir","funding_links":[],"categories":["Documentation"],"sub_categories":[],"readme":"# BlueBird\n\n[![Build Status](https://travis-ci.org/KittyHeaven/blue_bird.svg?branch=master)](https://travis-ci.org/KittyHeaven/blue_bird)\n[![Hex.pm](https://img.shields.io/hexpm/v/blue_bird.svg)](https://hex.pm/packages/blue_bird)\n[![Coverage Status](https://coveralls.io/repos/github/KittyHeaven/blue_bird/badge.svg?branch=master)](https://coveralls.io/github/KittyHeaven/blue_bird?branch=master)\n[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/rhazdon/blue_bird/blob/master/LICENSE)\n[![Deps Status](https://beta.hexfaktor.org/badge/all/github/KittyHeaven/blue_bird.svg)](https://beta.hexfaktor.org/github/KittyHeaven/blue_bird)\n\n`BlueBird` is an api documentation builder for the [Phoenix framework](http://www.phoenixframework.org/). The documentation is generated in the\n[API Blueprint](https://apiblueprint.org/) format from annotations in\nyour controllers and from automated tests.\n\n## Installation\n\n1. Add BlueBird to your mix.exs dependencies:\n\n```elixir\ndefp deps do\n  [{:blue_bird, \"~\u003e 0.4.0\"}]\nend\n```\n\n2. Run `mix deps.get` to fetch the dependencies:\n\n```bash\n$ mix deps.get\n```\n\n3. In `test/test_helper.exs`, start the BlueBird logger with `BlueBird.start()`\n   and configure ExUnit as follows:\n\n```elixir\nBlueBird.start()\nExUnit.start(formatters: [ExUnit.CLIFormatter, BlueBird.Formatter])\n```\n\n4. Add the following lines to `config.exs`:\n\n```elixir\nconfig :blue_bird,\n  docs_path: \"priv/static/docs\",\n  theme: \"triple\",\n  router: AppWeb.Router\n```\n\n5. Add `blue_bird_info` to your `mix.exs` to add global information:\n\n```elixir\ndef blue_bird_info do\n  [\n    host: \"https://api.acme.com\",\n    title: \"ACME API\",\n    description: \"\"\"\n                 API requires authorization. All requests must have valid\n                 `auth_token`.\n                 \"\"\"\n  ]\nend\n```\n\n6. Add `BlueBird.Controller` to your `web.ex` controller function:\n\n```elixir\ndef controller do\n  quote do\n    ...\n    use BlueBird.Controller\n    ...\n  end\nend\n```\n\n7. Install aglio:\n\n```bash\n$ npm install aglio -g\n```\n\n## Usage\n\n### Router\n\nBy default, documentation is only generated for routes that use the `:api`\npipeline. You can configure which pipelines to use in the configuration.\n\n```elixir\nconfig :blue_bird,\n  pipelines: [:something_else]\n```\n\n### Controller\n\nUse the `api/3` macro to annotate your controller functions.\n\n```elixir\ndefmodule AppWeb.CommentController do\n  use AppWeb, :controller\n\n  api :GET, \"/posts/:post_id/comments\" do\n    title \"List comments\"\n    description \"Optional description\"\n    note \"Optional note\"\n    warning \"Optional warning\"\n    parameter :post_id, :integer, [description: \"Post ID or slug\"]\n  end\n  def index(conn, %{\"post_id\" =\u003e post_id}) do\n    ...\n  end\nend\n```\n\nBlueBird groups routes by controller. By default, it uses the controller names\nas group names in the headings. You can change the group name of a controller\nby adding the `apigroup` macro to your controller modules. The macro can also\nbe used to add a group description.\n\n```elixir\ndefmodule AppWeb.CommentController do\n  use AppWeb, :controller\n\n  apigroup \"Blog Comments\", \"some description\"\n  ...\nend\n```\n\n### Tests\n\nIn your tests, select which requests and responses you want to include in the\ndocumentation by saving `conn` to `BlueBird.ConnLogger`:\n\n```elixir\ntest \"list comments for post\", %{conn: conn} do\n  insert_posts_with_comments()\n\n  conn = conn\n  |\u003e get(comments_path(conn, :index))\n  |\u003e BlueBird.ConnLogger.save(title: \"Without params\")\n\n  assert json_response(conn, 200)\nend\n```\n\n## Generating the documentation\n\nFirst, run your tests:\n\n```bash\n$ mix test\n```\n\nAll `conn`s that were saved to the `ConnLogger` will be processed. The\ndocumentation will be written to the file `api.apib` in the directory specified\nin the configuration. The file uses the [API Blueprint](https://apiblueprint.org) format.\n\nThere are [several tools](https://apiblueprint.org/tools.html#renderers) that\ncan render `apib` files to html. `BlueBird` has a mix task which uses\n[Aglio renderer](https://github.com/danielgtaylor/aglio) to generate an html\ndocument from the generated `apib` file.\n\n```\n$ mix bird.gen.docs\n```\n\nIf you use BlueBird in an umbrella app, you must run the command from within\nthe folder of the child app (e.g. `apps/myapp_web`).\n\n## Configuration\n\n### `config.exs`\n\nThe configuration options can be setup in `config.exs`:\n\n```elixir\nconfig :blue_bird,\n  docs_path: \"priv/static/docs\",\n  theme: \"triple\",\n  router: YourAppWeb.Router,\n  pipelines: [:api],\n  ignore_headers: [\"not-wanted\"]\n```\n\n#### Options\n\n- `docs_path`: Specify the path where the documentation will be generated. If\n  you want to serve the documentation directly from the `phoenix` app, you can\n  specify `priv/static/docs`. If you use BlueBird within an umbrella app, the\n  path is relative to the root folder of the umbrella app.\n- `theme`: The [Aglio](https://github.com/danielgtaylor/aglio) theme to be used\n  for the html documentation.\n- `router`: The router module of your application.\n- `pipelines` (optional): Only routes that use the specified router pipelines\n  will be included in the documentation. Defaults to `[:api]` if not set.\n- `ignore_headers` (optional): You can hide certain headers from the\n  documentation with this option. This can be helpful if you serve your\n  application behind a proxy. If the value is a list of strings as above, the\n  specified headers will be hidden from both requests and responses. If you\n  want to hide different headers from requests and responses, you can use a map\n  instead: `ignore_headers: %{request: [\"ignore-me\"], response: [\"and-me\"]}`.\n- `trim_path` (optional): Allows you to remove a path prefix from the docs. For\n  example, if all your routes start with `/api` and you don't want to display\n  this prefix in the documentation, set `trim_path` to `\"/api\"`.\n\n### `blue_bird_info()`\n\n#### Options\n\n- `host`: API host.\n- `title`: Documentation title (can use Blueprint format).\n- `description`: Documentation description (can use Blueprint format).\n- `terms_of_service` (optional): Terms of service, string.\n- `contact` (optional)\n  - `name` (optional)\n  - `url` (optional)\n  - `email` (optional)\n- `license` (optional)\n  - `name` (optional)\n  - `url` (optional)\n\n## FAQ\n\n### Route is not generated after adding API annotations to the controller\n\nPlease make sure that the route you are using in the annotation matches the\nroute from the `phoenix router` (including params) exactly. Run\n`mix phoenix.routes` (or `mix phx.routes` if Phoenix \u003e= 1.3) and compare the\nroutes.\n\nAlso note that only routes that use the api pipeline (or the pipelines you\nconfigured in config.exs) will be added to the documentation.\n\n### Body Parameters are not rendered\n\nBlueBird reads the `body_params` from `%Plug.Conn{}`. This map is only set if\n`body_params` is a binary.\n\n#### Example\n\n```elixir\npost build_conn(), \"/\", Poison.encode! %{my: data}  # recommended\npost build_conn(), \"/\", \"my=data\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhazdon%2Fblue_bird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhazdon%2Fblue_bird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhazdon%2Fblue_bird/lists"}