REST API documentation with Swagger, SpringMVC and AngularJS.

New front-end frameworks like AngularJS consume Rest API’s. As a result, we develop more Rest web services than SOAP ones.
Unlike SOAP, REST doesn’t provide wsdl (Web Services Description Language) to provide a definition of how the webservice works.

Well documented API make life easier for front-end developer and it is essential requirement for defining API’s success.

Swagger is one of the most popular frameworks for Restful API documentation. It provides documentation generation and a user interface to display the documentation in an awesome manner.

This post presents how to generate Rest API documentation for a Spring MVC project using Swagger, springfox and angular-swagger-ui.

You can download the source code of this article in this link : And you can test it here

Add Springfox dependency


Add configuration

All what you have to do as a Spring configuration is to add @EnableSwagger2 annotation to your existent MVC config class.

@ComponentScan(basePackages = { "com.mycompany.myproject.web.controller" })
public class MvcConfig extends WebMvcConfigurerAdapter {
  // Existent configuration code


Next, you can add swagger annotation to your controller.

Swagger annotation are not mandatory, springfox generate swagger docs for Spring MVC controllers. But, you may need them to customize your Rest API documentation.

For more information about swagger annotation, visit this link.

@Api(description = "Users management API")
public class UserController {
  // Existent controller code

Test swagger code generation

If you request this URL (http://localhost:8080/v2/api-docs) in your browser, you will get json format swagger documenation.

      "description":"Api Documentation",
      "title":"Api Documentation",
         "name":"Contact Email"
         "name":"Apache 2.0",
         "description":"Users management API"
   // other details ...

Display documentation

Swagger provides user interface (Swagger UI) that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API.

In this post, we will use an AngularJS implementation of Swagger UI (angular-swagger-ui). The advantage of this choice is that we can integrate the documentation page to an existent AngularJS project.

Add a angular-swagger-ui dependency

In this sample we use webjars. You may need to add webjars config to your Spring MVC project. For more information visit this link.


Run the angular-swagger-ui in this link:

Next, copy the swagger api url to the input and click on the “explore” button.


Integrate the Swagger-UI to your AngularJs application

Add angular-swagger-ui dependency to your Html page.

<!DOCTYPE html>
<html ng-app="myApp">
<head lang="en">
    <meta charset="UTF-8">
    <link href="webjars/bootstrap/3.3.2/css/bootstrap.min.css" rel="stylesheet" >
    <link href="webjars/angular-swagger-ui/0.2.3/dist/css/swagger-ui.min.css" 
          rel="stylesheet" >

<div class="navbar navbar-default">
    <div class="navbar-header">
		<!-- extra html code ... -->
    <div class="navbar-collapse collapse navbar-responsive-collapse">
        <ul class="nav navbar-nav">
            <li><a href="#/users">Users</a></li>
            <li><a href="#/apiDoc">API Doc.</a></li>

<div class="container">
	<section ng-view=""></section>

<script src="webjars/jquery/2.1.1/jquery.js"></script>
<script src="webjars/bootstrap/3.3.2/js/bootstrap.min.js"></script>
<script src="webjars/angular-swagger-ui/0.2.3/dist/scripts/swagger-ui.min.js"></script>
<script src="resources/js/app.js"></script>


Create a new html page with the source code bellow.

    .swagger-validator {
        display: none;
<div class="well page">
    <h3 ng-show="isLoading">loading ...</h3>
    <div swagger-ui url="swaggerUrl" loading="isLoading" parser="json" 
         api-explorer="true"  error-handler="myErrorHandler">

Modify the javascript code:

  • Include swaggerUi as a dependency.
  • Add a path apiDoc to the routeProvider.
  • Add an ApiDocController.
    .module('myApp', ['ngResource', 'ngRoute', 'ngSanitize', 'swaggerUi'])
    .config(function ($routeProvider) {
        $routeProvider.when('/users', {
            templateUrl: 'partials/users.html',
            controller: 'UsersController',
        }).when('/apiDoc', {
            templateUrl: 'partials/apiDoc.html',
            controller: 'ApiDocController'
            redirectTo: '/users',
    .service('UsersService', function ($log, $resource) {
        return {
            getAll: function () {
                var userResource = $resource('users', {}, {
                    query: {method: 'GET', params: {}, isArray: true}
                return userResource.query();
    .controller('UsersController', function ($scope, $log, UsersService) {
        $scope.users = UsersService.getAll();
    .controller('ApiDocController', function ($scope) {
        // init form
        $scope.isLoading = false;
        $scope.url = $scope.swaggerUrl = 'v2/api-docs';
        // error management
        $scope.myErrorHandler = function (data, status) {
            alert('failed to load swagger: ' + status + '   ' + data);

        $scope.infos = false;

Deploy and run your application. If you access the “API Doc.” page, you will get a web page as shown below. You can test the sample application of this post in this link.



Springfox and Swagger are great tools for generating your Rest API documentation. They are easy to integrate in your project and they provide a rich documentation that reduces costs and dramatically improves developer adoption.

However, the current version 2.2.2 of Springfox doesn’t support the generation of documentation of spring-data-rest Rest API. In this case, you have to consider Spring REST Docs project which is a serious alternative to swagger.

2 thoughts on “REST API documentation with Swagger, SpringMVC and AngularJS.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s