On this page:
  • What is a documentation generator?
  • What are the benefits of automating documentation generation?
  • Limitations of documentation generators
  • Best static analysis documentation generators
  • Best API documentation generator tools

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.

Tips from the expert

Omer Rosenbaum
Omer Rosenbaum
CTO & Co-founder at Swimm
In my experience, here are tips that can help you better documentation generation tools:
1.
Know what a documentation generator is: A documentation generator is a tool that automatically creates documentation from your code. This can be useful for creating documentation for APIs or other software, saving you time and helping keep the documentation up-to-date as your code changes.
2.
Understand the pros and cons of using a generator: Using a documentation generator saves time and effort, especially for complex projects. However, these tools can only document what’s in the code—they can’t explain why certain decisions were made or cover business logic. You might still need to add some manual notes to explain the bigger picture.
3.
Pick the right tool for your needs: Different tools work better for different types of documentation. For example, Swimm and Doxygen are good for internal documentation because they work directly with your codebase. For API documentation, tools like SwaggerUI, Redoc, and RapiDoc are great because they make the documentation easy to read and interact with. Choose a tool that fits your specific needs and works well with your team’s workflow.

Best static analysis documentation generators

These are tools that can generate documentation based on code artifacts. These tools are mainly used for internal developer documentation.

1. Swimm

Swimm is a documentation platform that is transforming the way enterprise engineers discover and generate documentation about code. Utillzing Generative AI combined with years of experience in the documentation and knowledge sharing space, Swimm can generate overview documentation for entire repositories in just a few clicks.

Auto-docs works by using static code analysis combined with relational ranking algorithms to construct a complex, logical understanding of the relationships that exists within your codebase and their relative importance. Auto-docs is language agnostic, including support for languages like Cobol and Assenbly.

Take a look at Auto-docs in action:

Auto-docs gives developers the benefits of great documentation, without the considerable time and resources it would take to write the docs, and then maintain and keep them up to date over time. Auto-docs turns the dreaded thought of creating and maintaining effective documentation into a 1-time automated solution. It’s like the gift that keeps on giving.

In addition to Auto-docs, Swimm has created a number of features that generate documentation for developers as a natural part of the SDLC. Here are a few other ways you can create documentation in the click of a button:

  • Snippets2doc generates documentation from selected code snippets
  • PR2doc creates a document based on the changes made in a specific pull request
  • Branch2doc enables developers to generate a document based on changes made to a particular branch
  • Chat2doc utilises answers from /ask (the Swimm AI assistant) to create documentation based on questions and answers

Get started with Swimm today!

2. Doxygen

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

Swagger UI

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

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

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

Rapiddoc

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).