AP Studio Documentation Generation

Mark J. Norton

**This blog post has been updated. For an updated version of AP Studio Documentation blog post, please click here**

Documentation is something most programmers would willingly avoid given even the smallest chance.  Most see it as a distraction from what they do, which is write code.  If asked directly, however, programmers will usually admit the importance of documentation for the client, for team members, for those who follow and even (whisper it) themselves.  With a very little bit of extra effort, however, MuleSoft developers can take advantage of the built in documentation generation in AnyPoint Studio.

The concept of documentation embedded in code has been around for quite some time.  Since MuleSoft uses Java extensively in developing their own products, most MuleSoft developers are familiar with JavaDoc, a documentation generation utility introduced in 1995 (https://en.wikipedia.org/wiki/Javadoc).  JavaDoc generates high quality documentation for Java interfaces, classes, and objects formatted as a set of HTML pages.

MuleSoft AnyPoint Studio provides documentation generation in a similar manner.  Once code is complete, select the AP Studio project and use the file menu to select Export Studio Documentation.

You will be prompted for a location to save the results.  To illustrate the results, a simplistic application was created with three elements:  an HTTP listener, a database request, and a data formatter, which is included in the illustration above.

The result is an index.html page that looks like this:

All flows are listed on the left.  There is only a single flow in this example, but if there were more, they would be included here.

At the top right,  a graphical representation of the example flow is shown, the same one you would see in AP Studio. Each element is then broken out below for further detail.  Section 1 in the blue box shows one of these elements, a database operation that fetches records based on a simple query.  The element is labeled as part of the “get_persons_Flow”, along with the label specified by the developer, “All Persons” in this case.  Note the text at the bottom of the section that reads “To protect privacy …”.  This information was added by the developer using the Notes tab of the element in AP Studio:

This is very similar to the annotations supported by JavaDoc that allows additional information to be included in the code to further clarify the documentation generated later.

Element in the documentation includes a clickable link that reveals the XML associated with it.

This also illustrates how the description note is included in the XML definitions.

Overall, the results are clean and professional looking.  While all of the important information is included, there is room for improvement.  For example, error handling does not have any documentation generated, though it can be viewed by viewing the whole flow XML.  I would love to see additional resources included, even if just as a list.  These could include POM files, schemas, API definitions, property files, etc.  Finally, there should be an option to generate for specifically for PDF so that it can be printed and/or distributed.  Fields can be expanded manually and the page printed to PDF, but these extra steps shouldn’t be needed.

While not perfect, documentation generated by AP Studio is a quick and easy solution for documentation required by a client.  A little descriptive work by the developer results in a doc set that describes the application, how it is broken down, and (roughly) how it works.