Spring MVC endpoint documentation with Spring Boot

A long time ago I had posted about a way to document all the uri mappings exposed by a typical Spring MVC based application. The steps to do this however are very verbose and requires a fairly deep knowledge of some of the underlying Spring MVC components.

Spring Boot makes this kind of documentation way simpler. All you need to do for a Spring-boot based application is to activate the Spring-boot actuator. Adding in the actuator brings in a lot more production ready features to a Spring-boot application, my focus however is specifically on the endpoint mappings.

So, first to add in the actuator as a dependency to a Spring-boot application:

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

and if the Spring-Boot app is started up now, a REST endpoint at this http://machinename:8080/mappings url should be available which lists out all the uri's exposed by the application, a snippet of this information looks like the following in a sample application I have:

{
  "/**/favicon.ico" : {
    "bean" : "faviconHandlerMapping"
  },
  "/hotels/partialsEdit" : {
    "bean" : "viewControllerHandlerMapping"
  },
  "/hotels/partialsCreate" : {
    "bean" : "viewControllerHandlerMapping"
  },
  "/hotels/partialsList" : {
    "bean" : "viewControllerHandlerMapping"
  },
  "/**" : {
    "bean" : "resourceHandlerMapping"
  },
  "/webjars/**" : {
    "bean" : "resourceHandlerMapping"
  },
  "{[/hotels],methods=[GET],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public java.lang.String mvctest.web.HotelController.list(org.springframework.ui.Model)"
  },
  "{[/rest/hotels/{id}],methods=[GET],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public mvctest.domain.Hotel mvctest.web.RestHotelController.get(long)"
  },
  "{[/rest/hotels],methods=[GET],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public java.util.List<mvctest.domain.Hotel> mvctest.web.RestHotelController.list()"
  },
  "{[/rest/hotels/{id}],methods=[DELETE],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public org.springframework.http.ResponseEntity<java.lang.Boolean> mvctest.web.RestHotelController.delete(long)"
  },
  "{[/rest/hotels],methods=[POST],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public mvctest.domain.Hotel mvctest.web.RestHotelController.create(mvctest.domain.Hotel)"
  },
  "{[/rest/hotels/{id}],methods=[PUT],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public mvctest.domain.Hotel mvctest.web.RestHotelController.update(long,mvctest.domain.Hotel)"
  },
  "{[/],methods=[],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public java.lang.String mvctest.web.RootController.onRootAccess()"
  },
  "{[/error],methods=[],params=[],headers=[],consumes=[],produces=[],custom=[]}" : {
    "bean" : "requestMappingHandlerMapping",
    "method" : "public org.springframework.http.ResponseEntity<java.util.Map<java.lang.String, java.lang.Object>> org.springframework.boot.autoconfigure.web.BasicErrorController.error(javax.servlet.http.HttpServletRequest)"
  },
  
  ....

Note that by default the json is not formatted, to get a formatted json just ensure that you have the following entry in your application.properties file:

http.mappers.json-pretty-print=true

This listing is much more comprehensive than the listing that I originally had.

The same information can of course be presented in a better way by rendering it to html and I have opted to use angularjs to present this information, the following is the angularjs service factory to retrieve the mappings and the controller which makes use of this factory to populate a mappings model:

app.factory("mappingsFactory", function($http) {
    var factory = {};
    factory.getMappings = function() {
        return $http.get(URLS.mappingsUrl);
    }
    return factory;
});

app.controller("MappingsCtrl", function($scope, $state, mappingsFactory) {
    function init() {
        mappingsFactory.getMappings().success(function(data) {
           $scope.mappings = data;
        });
    }

    init();
});

The returned mappings model is essentially a map of a map, the key of the map being the uri path exposed by Spring-Boot application and the values being the name of the bean handling the endpoint and if available the details of the controller handling the call, this can be rendered using a template of the following form:

<table class="table table-bordered table-striped">
    <thead>
    <tr>
        <th width="50%">Path</th>
        <th width="10%">Bean</th>
        <th width="40%">Method</th>
    </tr>
    </thead>
    <tbody>
    <tr ng-repeat="(k, v) in mappings">
        <td>{{k}}</td>
        <td>{{v.bean}}</td>
        <td>{{v.method}}</td>
    </tr>
    </tbody>
</table>

the final rendered view of the endpoint mappings is displayed in the following way:

Here is a sample github project with the rendering implemented: https://github.com/bijukunjummen/spring-boot-mvc-test