Miredot

How Miredot works

One of the tools you can use to generate API documentation from source -- as long as your source is Java-based -- is Miredot.

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:

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.

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

Activity: Explore Miredot's output

1. First 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.

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.