What is a documentation generator?
A documentation generator is a tool that programmatically generates technical and software documentation. Most commonly, auto-generated documentation is used for application programming interfaces (APIs), intended for a developer audience. A generator can create documentation from source code and other files, including binaries.
Different documentation generation tools are available for different types of documentation. Some tools are better suited for internal documentation, while others are more useful for external documentation. Likewise, the tool you choose will depend on the expertise required to use your documentation (i.e., if it is highly technical and detailed or high-level).
This is part of a series of articles about documentation tools.
What are the benefits of automating documentation generation?
APIs are a reliable mechanism to connect different applications and provide additional benefits such as rapid deployment, customizability, and cost optimization. APIs with auto-generated documentation can be deployed to end users faster and improve the user experience. They also improve productivity within software development teams tasked with creating and updating the documentation.
For internal documentation, generating docs automatically saves time from the developers who would otherwise write the documents themselves. Automatic generators may also help clarify parts of the codebase that the current developers on the team don’t know well enough to contribute to, let alone to document.
Limitations of documentation generators
Document generators can only deduce information that exists in the code. They can’t deduce business logic, design decisions, let alone the reasons not to implement things in a certain way. In addition, automatic generators don’t always separate the wheat from the chaff, as they may treat all code in the same manner.
Best static analysis documentation generators
These are tools that can generate documentation based on code artifacts. They are mainly useful for internal developer documentation.
1. Swimm
Swimm is predominantly a tool for internal documentation, i.e. documentation that helps software teams manage and transfer knowledge about how their code works and why it was built the way that it was.
Unlike most other tools, Swimm can generate documentation without the need to conform to certain code structures or conventions or a need for adding inline code comments.
Swimm includes a growing number of algorithms that use static analysis of the code to look for various patterns. Swimm then includes code snippets and tokens within its opinionated documentation templates. In some cases, the user is requested to add context where needed, for instance, adding explanations regarding certain decisions.
As a result, Swimm selects code patterns that are important to document, and generates documents that are optimized for developers who need to contribute to the codebase.
Documentation generated by Swimm is language dependent and may include:
- Explanations of recurring patterns, and how to add new instances of such patterns.
- Overview documents describing important components.
- Main flows within the application.
- And more.
2. Doxygen
Doxygen is a documentation generator tool that can extract documentation from source code and other documentation files and generate it in a structured format, such as HTML, PDF, or LaTeX. Doxygen can extract documentation by using special comments in the source code that tell Doxygen how to interpret the documentation.
It provides a wide range of customization options, including the ability to specify the output format, the level of detail to include in the documentation, and the appearance of the documentation. It integrates well with popular integrated development environments (IDEs) and can be configured through a configuration file or through special comments in the source code.
Best API documentation generator tools
3. SwaggerUI
License: Apache License 2.0
Repository: https://github.com/swagger-api/swagger-ui
Swagger UI lets anyone (whether a developer or end-user) visualize and interact with API resources without accessing the relevant implementation logic. It automatically generates documentation from the OpenAPI specification and provides visuals to facilitate client-side consumption and back-end implementation.
Swagger UI is human-centric, allowing end developers to interact and experiment with all operations exposed by the API—it focuses on usability and readability of the documentation. The tool is fully customizable, providing access to source code to let you modify and style your UI. Finally, there are no dependencies—the UI adapts to any local or web-based development environment.
4. Redoc
License: MIT License
Repository: https://github.com/Redocly/redoc
Redoc is an open source tool for generating API documentation according to the OpenAPI specification. It creates clean, customizable documents in an attractive design with three panels. Markdown support makes it easy to write and style comments.
Redoc uses the OpenAPI specification to generate documents within your browser, so no server is required. Redoc includes a CLI tool for inspecting all Open API definitions based on rules that ensure you adhere to OpenAPI best practices. When you are ready to publish your documentation, there’s only one command to run.
5. DapperDox
License: GNU General Public License v3.0
Repository: https://github.com/DapperDox/dapperdox
DapperDox is an open source, out-of-the-box solution for API documentation. It is a highly flexible tool that allows you to design pages according to your needs. Like Redoc, DapperDox supports Markdown.
DapperDox has a clean, two-column user interface—the first column contains the navigator and the second column contains the details of the API methods. You can also customize page themes ( a feature not provided by Redoc).
With DapperDox, you can write complete documentation using GitHub Flavored Markdown. You can document many API specifications as a set of products with cross-referencing. It also lets you place your content seamlessly into automatically generated references.
The tool integrates a built-in API browser with your authentication systems and APIs. It can proxy the development platform to enable fully integrated API key management. You can choose from several themes or create a new one.
6. RapiDoc
License: MIT License
Repository: https://github.com/rapi-doc/RapiDoc
RapiDoc is an interactive API documentation tool that lets you create visually appealing documents using the OpenAPI specification. It is flexible, enabling the customization of themes, fonts, and colors. You can embed your documentation into HTML code or embed external code into your documentation.
RapiDoc includes an easy-to-use, out-of-the-box console for making API calls and testing APIs. You can use JavaScript to modify its attributes, just like with HTML. Similar to SwaggerUI, a single-column view and collapsible bars contain the console and JSON payloads.
Learn more in our detailed guide to best documentation tools (coming soon).
