/bureaucrat

Generate Phoenix API documentation from tests

Primary LanguageElixirThe UnlicenseUnlicense

Bureaucrat

Bureaucrat is a library that lets you generate API documentation of your Phoenix app from tests.

Installation

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

Usage

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.

Configuration

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 under YourApp.Api.V1 namespace to be written to web/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.