Generate Phoenix API documentation automatically from ExUnit tests, supporting Markdown, Swagger/Slate, API Blueprint, and Postman formats.
Bureaucrat is a library for Elixir Phoenix applications that automatically generates API documentation from ExUnit tests. It captures connection structs and test assertions to produce comprehensive, up-to-date documentation, eliminating the need for manual updates. The library supports multiple output formats including Markdown, Swagger/Slate integration, API Blueprint, and Postman collections.
Elixir developers building Phoenix web applications who need to maintain accurate API documentation. It is particularly useful for teams practicing test-driven development and those requiring documentation for both HTTP endpoints and Phoenix Channels.
Developers choose Bureaucrat because it ensures documentation is always synchronized with the actual API behavior by deriving it directly from test executions. Its unique selling point is the elimination of manual documentation maintenance through test-driven documentation, with flexible output formats and support for Phoenix Channels.
Generate Phoenix API documentation from tests
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Generates documentation directly from ExUnit tests, capturing actual request/response data in connection structs to ensure docs are always synchronized with code behavior, as shown in the basic usage example.
Supports Markdown, Swagger/Slate integration, API Blueprint, and Postman collections, offering flexibility for different documentation workflows, with detailed configuration options for each writer.
Includes specialized helpers like doc_push and doc_broadcast_from to document real-time channel interactions, a unique feature for Phoenix applications, though limited to Markdown output.
Offers Bureaucrat.Macros to automatically pipe doc() into Phoenix.ConnTest macros, minimizing repetitive code in tests, as described in the automatic piping section.
Requires multiple configuration steps such as modifying test_helper.exs, importing helpers in conn_case.ex, and setting environment variables, which can be daunting and error-prone for new users.
Documentation quality hinges on the completeness and success of test runs; incomplete tests or failures can lead to missing or inaccurate docs, and generation only triggers when tests are run with DOC=1.
Phoenix Channels documentation is only supported with the MarkdownWriter and to a default path, restricting flexibility for teams wanting other formats like API Blueprint or Postman for channels.