REST Service Documentation

Overview

The main goal of documenting the REST services is to have a common reference point for front-end and back-end developers to integrate the user interface to the services. A secondary goal is to provide a reference for 3rd party integrators that may want to create their own applications that use the service interfaces directly.

Static Documentation

Static Javadoc-style documentation is generated at build time using the miredot maven plugin. This is a commercial plugin that offers a limited version for free. We've incorporated this component and the documentation it generates is clean and accurate. As a separate task, we'll look at publishing the documentation as part of our build process. For now the documentation is generated as part of the main build and can be found here:

mvn clean install
cd we99-domain/target/miredot
open index.html

Interactive Documentation

Interactive documentation is provided via the Swagger.io project. This library provides annotations that are added to your REST services in order to make them known to the documentation generator. There is a REST service installed for Swagger as part of our application that handles requests for documentation and produces a Swagger defined format for describing the service. We've also integrated the swagger-ui module which is a set of HTML and JS files that can render the Swagger JSON format as an interactive form for driving the REST services. The UI will parse the Swagger JSON received from the Swagger REST service and dynamically assemble a list of REST Service definitions with controls for invoking the services.

You can access swagger when the web app is running by visiting the following URL:

http://localhost:8080/we99/swagger/?url=http://localhost:8080/we99/services/rest/api-docs

Note the format of the URL:

• first part accesses the swagger folder in our web app and loads the index.html page there
• the url= query param tells the JS in the index.html page where to find the REST services in WE99

Packaging

All of the source files for swagger were copied from the swagger.io GitHub page's distribution folder. Typically, we'd want to separate this files from our build and package them as a zip or similar in a maven repository. However, there's nothing readily available in Maven Central and we don't have a local maven repo to use so the files are inlined within our project. This isn't ideal but it works for now.