By Mark Norton
Documentation is something most programmers would willingly avoid given the smallest chance. Most see it as a distraction from what they do, which is writing code. If asked directly, however, most programmers will admit that documentation is important for the client, team members, those who follow and even (whisper it) themselves. With a little bit of extra effort, MuleSoft developers can take advantage of the built-in documentation generations in AnyPoint Studio.
This 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. JavaDoc generates high quality documentation for Java interfaces, classes and objects formatted as a set of HTML pages,
Examples
MuleSoft AnyPoint Studio provides documentation generation in a similar manner. To illustrate how this works a simple application was created with three elements: an HTTP listener, a database request, and a data formatter.
Adding Additional Information
Additional information can added using the Notes tab in flow elements. Here, additional information is added to the database query:
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.
The “doc:description” parameter is only include if one is specified.
Documentation Generation
Once code is complete and ready for document generation, click on the Export Studio Documentation icon:
A dialog box is displayed to select a folder to save results in:
Confirm the folder creation (it will overwrite a previous version, if it exists):
Viewing the Generated Documentation
Results are saved in the folder as a set of HTML files, plus graphics.
Open the “index.html” file in a browser. You’ll see a formatted view of the generated documentation:
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 as well.
A graphical representation of the example flow is shown, the same one you would see in AP Studio. Each processing element is then broken out below for further detail. Two are shown above.
The first is an HTTP listener inbound endpoint that listens on port 8081 (defined by the HTTP configuration) and the path ‘/persons”.
The second is a database operation that fetches records based on a simple query. The element is labeled as part of the “person_sapiFlow”, along with the label specified by the developer, “All Persons” in this case. Note the text at the bottom of the selection that reads “Fields for the person table include …”. This information was added by the developer using the Notes tab of the element in AP Studio:
**Note that the final processing element, “json:object-to-json-transformer” is not included in the documentation, Simple processing elements are not included to improve readability.
Conclusion
Overall, the results are clean and professional looking. While all of the important information is included, there is a room for improvement. For example, error handling does not have any documentation generated, though it can be 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 and property files, just to name a few. Finally, there should be an option to generate specifically for PDF so that the file can be printed and/or distributed. In the current program, developers can expand fields manually and print the page as a PDF this way, but all these extra steps shouldn’t be necessary.
While not perfect, documentation generated by AP Studio is a quick and easy solution for when documentation is 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.
About The Author
Mark Norton is a senior integration specialist at ArganoMS3 with over 15 years of API design and implementation experience in support of higher education, retail, healthcare, telecommunications, IT, and other vertical markets. As a senior architect, Mark guides the future direction of clients by conducting architect design reviews and consulting on tactical directions. He has experience with MuleSoft, RedHat JBoss, and Java Servlet API Platforms.
Leave a Reply