Merge pull request #43 from KittyHeaven/dev

Dev

.travis.yml

@@ -1,23 +1,28 @@
 language: elixir
 
 elixir:
-  - 1.4.0
-  - 1.4.1
-  - 1.4.2
+  - 1.4.5
+  - 1.5.0
+  - 1.5.1
+
+node_js:
+  - "6"
+  - "7"
+  - "8"
 
 otp_release:
-  - 18.0
-  - 18.1
-  - 18.2
-  - 18.3
   - 19.0
   - 19.1
   - 19.2
   - 19.3
+  - 20.0
 
 env:
   global:
     - MIX_ENV=test
 
+before_script:
+  - npm install -g aglio
+
 script:
   - mix do deps.get, deps.compile, coveralls.travis

CHANGELOG

@@ -1,5 +1,13 @@
 # Changelog BlueBird
 
+## v0.3.8
+
+- add `terms_of_service`, `contact` and `license` fields
+- add `bird.gen.examples` mix task for generating example tests with aglio
+  (for development)
+- take first steps to integrate swagger (nothing usable yet)
+- render api group description
+
 ## v0.3.7
 
 - fix FunctionClauseError in Formatter

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Djordje Atlialp
+Copyright (c) 2017 Djordje Atlialp, Mathias Polligkeit
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,32 +1,33 @@
 # BlueBird
 
-[![Build Status](https://travis-ci.org/rhazdon/blue_bird.svg?branch=master)](https://travis-ci.org/rhazdon/blue_bird)
+[![Build Status](https://travis-ci.org/KittyHeaven/blue_bird.svg?branch=master)](https://travis-ci.org/KittyHeaven/blue_bird)
 [![Hex.pm](https://img.shields.io/hexpm/v/blue_bird.svg)](https://hex.pm/packages/blue_bird)
-[![Coverage Status](https://coveralls.io/repos/github/rhazdon/blue_bird/badge.svg?branch=master)](https://coveralls.io/github/rhazdon/blue_bird?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/KittyHeaven/blue_bird/badge.svg?branch=master)](https://coveralls.io/github/KittyHeaven/blue_bird?branch=master)
 [![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/rhazdon/blue_bird/blob/master/LICENSE)
-[![Deps Status](https://beta.hexfaktor.org/badge/all/github/rhazdon/blue_bird.svg)](https://beta.hexfaktor.org/github/rhazdon/blue_bird)
+[![Deps Status](https://beta.hexfaktor.org/badge/all/github/KittyHeaven/blue_bird.svg)](https://beta.hexfaktor.org/github/KittyHeaven/blue_bird)
 
-`BlueBird` is a library written in the `Elixir` programming language for the [Phoenix framework](http://www.phoenixframework.org/).
-It lets you generate API documentation in the [API Blueprint](https://apiblueprint.org/) format from annotations in controllers and automated tests.
+`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.3.6"}]
+  [{:blue_bird, "~> 0.3.8"}]
 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 the results formatter as follows:
+and configure ExUnit as follows:
 
 ``` elixir
 BlueBird.start()
@@ -39,10 +40,10 @@ ExUnit.start(formatters: [ExUnit.CLIFormatter, BlueBird.Formatter])
 config :blue_bird,
   docs_path: "priv/static/docs",
   theme: "triple",
-  router: MyApp.Web.Router
+  router: AppWeb.Router
 ```
 
-5. Add `blue_bird_info` to your `mix.exs` to improve the generated docs:
+5. Add `blue_bird_info` to your `mix.exs` to add global information:
 
 ``` elixir
 def blue_bird_info do
@@ -77,13 +78,23 @@ $ 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 generate the specification for the controller action.
+Use the `api/3` macro to annotate your controller functions.
 
 ``` elixir
-defmodule App.CommentController do
-  use App.Web, :controller
+defmodule AppWeb.CommentController do
+  use AppWeb, :controller
 
   api :GET, "/posts/:post_id/comments" do
     title "List comments"
@@ -98,53 +109,20 @@ defmodule App.CommentController do
 end
 ```
 
-Optionally use the `apigroup` macro to set the resource group name and
-description.
+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 App.CommentController do
-  use App.Web, :controller
+defmodule AppWeb.CommentController do
+  use AppWeb, :controller
 
   apigroup "Blog Comments", "some description"
   ...
 end
 ```
 
-### Router
-
-Currently, BlueBird expects that the routes are piped through `:api`.
-
-``` elixir
-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
@@ -162,15 +140,22 @@ test "list comments for post", %{conn: conn} do
 end
 ```
 
-After you run your tests, documentation will be written to `api.apib` in the
-[API Blueprint](https://apiblueprint.org) format.
+## Generating the documentation
 
-```
+First, run your tests:
+
+``` bash
 $ mix test
 ```
 
-To generate an HTML documentation, use the convenience wrapper to the
-[Aglio renderer](https://github.com/danielgtaylor/aglio).
+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
@@ -181,15 +166,15 @@ the folder of the child app (e.g. `apps/myapp_web`).
 
 ## Configuration
 
-### `config.exs`:
+### `config.exs`
 
 The configuration options can be setup in `config.exs`:
 
 ```elixir
 config :blue_bird,
   docs_path: "priv/static/docs",
   theme: "triple",
-  router: YourApp.Web.Router,
+  router: YourAppWeb.Router,
   pipelines: [:api],
   ignore_headers: ["not-wanted"]
 ```
@@ -200,26 +185,36 @@ config :blue_bird,
   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](https://github.com/danielgtaylor/aglio).
-* `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.
+* `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()`:
+### `blue_bird_info()`
 
-**Options**:
+#### 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
 
@@ -230,12 +225,12 @@ 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.
+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 Parameter are not rendered
+### Body Parameters are not rendered
 
-BlueBird reads the `body_params` from `%Plug.Conn{}`. These map is only set if
+BlueBird reads the `body_params` from `%Plug.Conn{}`. This map is only set if
 `body_params` is a binary.
 
 #### Example

lib/blue_bird/apidoc.ex

@@ -5,8 +5,19 @@ defmodule BlueBird.ApiDoc do
   defstruct [
     title: "",
     description: "",
+    terms_of_service: "",
     host: "",
-    routes: []
+    contact: [
+      name: "",
+      url: "",
+      email: ""
+    ],
+    license: [
+      name: "",
+      url: ""
+    ],
+    routes: [],
+    groups: %{}
   ]
 
   @typedoc """
@@ -15,7 +26,22 @@ defmodule BlueBird.ApiDoc do
   @type t :: %BlueBird.ApiDoc{
     title: String.t,
     description: String.t,
+    terms_of_service: String.t,
     host: String.t,
-    routes: [BlueBird.Route.t]
+    contact: contact,
+    license: license,
+    routes: [BlueBird.Route.t],
+    groups: %{optional(String.t) => String.t}
   }
+
+  @type contact :: [
+    name: String.t,
+    url: String.t,
+    email: String.t
+  ]
+
+  @type license :: [
+    name: String.t,
+    url: String.t
+  ]
 end

lib/blue_bird/formatter.ex

@@ -15,7 +15,7 @@ defmodule BlueBird.Formatter do
   """
   use GenServer
 
-  alias BlueBird.Writer.Blueprint
+  alias BlueBird.Writer
   alias BlueBird.Generator
 
   @doc """
@@ -25,13 +25,12 @@ defmodule BlueBird.Formatter do
   def init(_config), do: {:ok, nil}
 
   @doc """
-  Event listener that triggers the generation of the api blueprint file on when
+  Event listener that triggers the generation of the api blueprint file when
   receiving a `:suite_finished` message by `ExUnit`.
   """
-  @spec handle_cast(request :: term, state :: term) ::
-    {:noreply, nil}
+  @spec handle_cast(request :: term, state :: term) :: {:noreply, nil}
   def handle_cast({:suite_finished, _run_us, _load_us}, _state) do
-    Generator.run() |> Blueprint.run()
+    Generator.run() |> Writer.run()
     {:noreply, nil}
   end
   def handle_cast(_, _), do: {:noreply, nil}