API Documentation For SpringBoot Using Swagger

While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation. Swagger primarily has few products which could be used to cover the entire life cycle of an API.

• Swagger UI - Visualize OpenAPI Specification definitions in an interactive UI
• Swagger Editor - API editor for designing APIs with the OpenAPI Specification
• Swagger Codegen - Generate server stubs and client SDKs from OpenAPI Specification definitions

Here I will explain how we could use the Swagger API documentation and Swagger UI for a SpringBoot project.

How to configure swagger with SpringBoot?

First, we need a SpringBoot application. You can use the spring initializr to generate a new project or you may use any current projects developed on SpringBoot. For this post, I will generate a SpringBoot project with the following properties. (You are free to use any configuration.)

Now we have a SpringBoot application. Let's add some API endpoints. I have added the following simple API endpoint using GET and POST methods.

package com.apiapp.springbootproject.controller;

import com.apiapp.springbootproject.model.DemoUser;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/demo")
public class DemoController {

    @GetMapping
    public ResponseEntity demoInitiator () {
        return ResponseEntity.ok("Response From Demo Initiator");
    }

    @PostMapping
    public ResponseEntity demoInitiator (@RequestBody DemoUser demoUser) {
        return ResponseEntity.ok("Got username as : "+demoUser.getUsername());
    }

}

Now we can configure Swagger to our SpringBoot project. First, we need to add the Swagger dependencies to the project.

compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'

With that, we have all the necessary dependencies to configure Swagger to SpringBoot, Let's focus on configuring Swagger into the application with the spring configuration. This could be done by adding the following class into the application.

package com.apiapp.springbootproject.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.ArrayList;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration // Add spring configuration behaviour to the config class
@EnableSwagger2 // Enabling Swagger Version 2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(generateAPIInfo())
            .select()
            //Here adding base package to scan controllers. This will scan only controllers inside
            //specific package and include in the swagger documentation
            .apis(RequestHandlerSelectors.basePackage("com.apiapp.springbootproject.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    //Api information
    private ApiInfo generateAPIInfo() {
        return new ApiInfo("Swagger Demo", "Implementing Swagger with SpringBoot Application", "1.0.0",
            "https://www.99xtechnology.com/", getContacts(), "", "", new ArrayList());
    }

    // Developer Contacts
    private Contact getContacts() {
        return new Contact("Chinthaka Dinadasa", "", "chinthakadi@99x.lk");
    }

}

All done! Let's make sure everything works well. You can check the Swagger API documentation and Swagger UI with a graphical interface via

http://localhost:8080/v2/api-docs - JSON formatted API Documentation

http://localhost:8080/swagger-ui.html - Swagger UI

Nice everything works perfectly!

Conclusion

I have explained the basic setup to configure Swagger to SpringBoot for API documentation. You can check other configurations like adding more API information into such configurations, testing your code with Swagger-UI, adding API endpoint descriptions with @ApiOperation, etc.

Comment here If you have any issues or check out the source code for this tutorial via https://github.com/chinthaka-dinadasa/swagger-with-springboot

Happy Coding.