Other tool options — a miscellaneous compilation

There are many different tools for creating documentation, and there’s no clear industry standard in this space. Different tools may better suit different environments, skill sets, and products. On this page, I’ve listed as many authoring tools as I can find that are related to the developer documentation space.

Readme.io

readme.io is an online hosted options for docs that offers one of the most robust, full-featured interfaces and options for developer docs available. If you consider how much time it requires to build, maintain, troubleshoot, etc., your own website, it really does make sense to consider an existing third-party platform where someone has already built all of this out for you.

To explore readme.io:

  1. Go to readme.io.
  2. Click the Sign Up button in the upper-right corner and sign up for an account.
  3. Click +Add Project. Then add a Project Name (e.g., Weather API), Subdomain (e.g., weather-api), and Project Logo. Then click Create.

    Project Settings

  4. Now check out the API doc configuration section. In the left sidebar, click Reference Docs, and then click API.

Although you can add your API information manually, you can also import an OpenAPI file. You can experiment by choosing one from the OpenAPI examples, such as this one.

Readme.io provides a number of wizard-like screens to move you through the documentation process, prompting you with forms to complete.

Readme.io provides a robust GUI for creating API documentation, in a way that is more extensive and well-designed than virtually any other platform available. The Readme output provides an interactive, try-it-out experience with endpoints:

The experience is similar to Swagger in that the response appears directly in the documentation. This API Explorer gives you a sense of the data returned by the API.

Readme.io is a pretty sweet platform, and you don’t have to worry about describing your API based on a specification based on either RAML or Swagger. But this also has downsides. It means that your doc is tied to the Readme.io platform. Additionally, you can’t auto-generate the output from annotations in your source code.

Additionally, if the cloud location for your docs isn’t an option, that may also pose challenges. Finally, there isn’t any content re-use functionality, so if you have multiple outputs for your documentation that you’re single sourcing, Readme.io may not be for you.

Even so, the output is sharp and the talent behind this site is top-notch. The platform is constantly growing with new features, so maybe all of this functionality will eventually be there.

Here are a few sample API doc sites built with Readme.io:

Miredot

Miredot is one of the tools you can use to generate reference API documentation from a Java source. Miredot is a plugin for Maven, which is a build tool that you integrate into your Java IDE. Miredot can generate an offline website that looks like this:

Miredot example

You can read the Getting started guide for Miredot for instructions on how to incorporate it into your Java project.

Miredot supports many annotations in the source code to generate the output. The most important annotations they support include those from Jax-rs and Jackson. See Supported Frameworks for a complete set of supported annotations.

Here’s an example of what these annotations look like. Look at the CatalogService.java file. In it, one of the methods is updateCategory.

You can see that above this method is a “doc block” that provides a description, the parameters, method, and other details:

    /**
     * Update category name and description. Cannot be used to edit products in this category.
     *
     * @param categoryId The id of the category that will be updated
     * @param category   The category details
     * @summary Update category name and description
     */
    @PUT
    @Path("/category/{id}")
    @Consumes({MediaType.APPLICATION_XML, MediaType.APPLICATION_JSON})
    public void updateCategory(@PathParam("id") Long categoryId, Category category);

Miredot consumes this information and generates an output.

To explore Miredot’s output:

  1. Browse the Miredot sample code.
  2. To see how this information gets rendered in the Miredot output, go to the Petstore example docs, expand Catalog > Category on the right, and then select PUT. Or go directly here.

Miredot update category

If you browse the navigation of Miredot’s output, it’s an interesting-looking solution. This kind of documentation might fit a Java-based REST API well.

But the authoring of the docs would really only work for Java developers. It wouldn’t work well for technical writers unless you’re plugged into the source control workflow.

Run in Postman button

The Run in Postman button provides a Run in Postman button that, when clicked, imports your API info into Postman so users can run calls using the Postman client.

To try out Run in Postman, first import your OpenAPI spec into Postman or enter your API information manually. Then see Create the Run in Postman button.

You can see the many demos here.

Here’s a demo using the sample Mashape weather API:

Postman provides a powerful REST API client that many developers are familiar with. It allows users to customize the API key and parameters and save those values. Although you don’t have the in-browser experience to try out calls, in many ways the Postman client is more useful. This is what developers often use to save and store API calls as they test and explore the functionality.

Especially if your users are already familiar with Postman, Run in Postman is a good option to provide (especially as one option of many for users to try out your API), as it allows users to easily integrate your API into a client they can use. It gives them a jumping off point where they can build on your information to create more detailed and customized calls.

If you don’t already have a “Try it out” feature in your docs, the Run in Postman button gives you this interactivity in an easy way, without requiring you to sacrifice the single source of truth for your docs.

The downside is that your parameter and endpoint descriptions don’t get pulled into Postman. Additionally, if users are unfamiliar with Postman, they may struggle a bit to understand how to use it. In contrast, the “Try it out” editors that run directly in the browser tend to be more straightforward and do a better job integrating documentation (including sample responses and the model they follow).

Spectacle

Spectacle is a Github project that builds an output from a Swagger file. The display provides a three-pane output similar to the Stripe or Slate docs. After you download the project files, you can build the display using Node simply by referencing your Swagger file.

Here’s a demo output. You can also see an output that uses the Mashape weather API file.

With almost no needed setup or configuration, you can have a world-class output and site for your API docs. As long as the OpenAPI spec that you integrate is fully detailed, the generated Spectacle site will be attractive and full-featured.

You can also build the Spectacle site without the frame so you can embed it into another site. However, in playing with this embed option, I found that I would have to create my own styles. If using the default styles in the full-site output, they most likely will overwrite or interfere with your host site’s appearance.

I’m also not sure if you can add your own doc pages to the Spectacle site.

Custom UX solutions

If you want to build a beautiful API doc website that rivals sites such as Parse.com (a custom-built solution that uses Prism.js, Sinatra, and other in-house tools), you’ll most likely need to involve a UX engineer to build it. Fortunately, building an API docs site is a solution that many UX engineers and other web developers are usually excited to tackle.

If you want to integrate your API documentation into your main website, ask the person designing your main website for strategies on integrating the doc site into it. This integration might allow you to leverage authentication (if needed) and other interaction points (such as with forums or support tickets).

Many custom websites are built using a variety of JavaScript, HTML, and CSS tools. Most likely you’ll be able to supply a batch of Markdown or HTML files to the web developer to integrate. Your UX developers will often be eager to design a custom solution to make your docs beautiful and seamlessly integrated with the rest of your content.

Getting help from your UX team

When I worked at Badgeville, our solution for publishing API documentation was to use custom scripts that pulled some information from source files and pushed them into templates.

The source files were stored on Github, and the writers could edit the descriptions of the parameters, fields, etc. Our developers created scripts that would look into the code of the source files and render content into JSON files in a specific structure.

Since we published all help content on a Drupal site, we hired a Drupal development agency that would take information from a JSON file and push the information into a custom-built template.

After the scripts were integrated into the Drupal site, we would have developers periodically run the build scripts to generate a batch of JSON files.

The upload scripts checked to ensure the JSON files were valid, and then they were pushed into the templates and published. Each upload would overwrite any existing content with the same file names.

If your documentation is published on a web-based CMS, you can probably find a development agency to create a similar script (if you don’t have in-house engineers to create them).

A lot of companies have custom solutions for their API documentation. Sometimes this kind of solution just makes sense and allows you to right-size the workflow to fit your specific information.

Tools that can read the OpenAPI specification

Many commercial API tools and platforms can read the OpenAPI specification and generate an interactive documentation website. See the list of tools on Swagger here.

More tools

I’ll be adding more tools here in the days to come…

  • readthedocs.org/com
  • mkdocs
  • hugo
  • slate
  • dexy

http://apidocjs.com/

Get new posts delivered straight to your inbox.

Subscriber count: 4,285