Bureaucrat is a library that lets you generate API documentation of your Phoenix app from tests.
First, add Bureaucrat to your mix.exs
dependencies:
defp deps do
[{:bureaucrat, "~> 0.1.4"}]
end
Then, update your dependencies:
$ mix deps.get
Next, in your test/test_helper.exs
you should start Bureaucrat and configure
ExUnit to use its formatter. You would probably like to keep the default
ExUnit.CLIFormatter
as well.
Bureaucrat.start
ExUnit.start(formatters: [ExUnit.CLIFormatter, Bureaucrat.Formatter])
And finally, import Bureaucrat helpers in test/support/conn_case.ex
:
defmodule Spell.ConnCase do
using do
quote do
import Bureaucrat.Helpers
end
end
end
Bureaucrat collects data from connection structs used in tests.
If you want a connection to be documented, pass it to the doc/1
funciton:
test "GET /api/v1/products" do
conn = conn()
|> get("/api/v1/products")
|> doc
assert conn.status == 200
end
Then, to generate the documentation file(s) run DOC=1 mix test
.
The default output file is web/controllers/README.md
.
The configuration options can be passed to Bureaucrat.start
:
Bureaucrat.start(
writer: Bureaucrat.MarkdownWriter,
default_path: "web/controllers/README.md",
paths: [],
env_var: "DOC",
controller_name_formatter: fn(name) ->
name
|> String.split(".")
|> List.last
end,
action_name_formatter: fn(name, _controller) ->
name
end,
doc_name: "My Server API Version I"
)
The available options are:
:writer
: The module used to generate docs from the list of captured connections.:default_path
: The path where the docs are written by default.:paths
: Allows you to specify different doc paths for some of your modules. For example[{YourApp.Api.V1, "web/controllers/api/v1/README.md"}]
will cause the docs for controllers underYourApp.Api.V1
namespace to be written toweb/controllers/api/v1/README.md
.:env_var
: The environment variable used as a flag to trigger doc generation.controller_name_formatter
: Anonymous function to modify the controller name before outputting it as a string.action_name_formatter
: Anonymous function to modify the action name before outputting as a string. May not receive controller name.doc_name
: String document name for title of document.