Swagger for Spring Boot How To

This is the note about how to make the swagger work together with Spring Boot. Swagger here is used as great tool to automatically create the Restful API html docs and testing API web UI.

1. Add swagger2 and UI to POM.XML

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger2</artifactId>
 <version>2.6.1</version>
 <scope>compile</scope>
 </dependency>

<dependency>
 <groupId>io.springfox</groupId>
 <artifactId>springfox-swagger-ui</artifactId>
 <version>2.6.1</version>
 <scope>compile</scope>
 </dependency>

2. Create a class for spring boot configuration for swagger:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import static springfox.documentation.builders.PathSelectors.regex;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

@Bean
 public Docket productApi() {
 return new Docket(DocumentationType.SWAGGER_2).select()
 .apis(RequestHandlerSelectors.basePackage("com.wayneshare.springboot.swaggerexample"))
 .paths(regex("/rest.*")).build().apiInfo(metaInfo());
 }

private ApiInfo metaInfo() {

ApiInfo apiInfo = new ApiInfo("WayneShare RestfulAPI", "Enable knowledge sharing ...", "1.0",
 "Terms of Service", new Contact("WayneShare", "https://www.wayneshare.com", "zhou_xiaowei@yahoo.com"),
 "", "");

return apiInfo;
 }
}

3. Then you can start run the application and goes to this URL http://localhost:8080/swagger-ui.html

You will see the swagger API html docs and can test over there.

4.  Try to change this part of code in config to see changes on the UI, then you will know the meta data reflecting on UI.

ApiInfo apiInfo = new ApiInfo("WayneShare RestfulAPI", "Enable knowledge sharing ...", "1.0",
 "Terms of Service", new Contact("WayneShare", "https://www.wayneshare.com", "zhou_xiaowei@yahoo.com"),
 "", "");

5. If you want to change the grouping name and description for one controller, then use @Api for you controller:

@RestController
@RequestMapping("/rest/account")
@Api(tags = "API 02", description = "Account info management")
public class AccountController {

6. Check these annotations too in case you want to change some meta on UI  and even the http return code desc. @ApiModelProperty @ApiOperation @ApiResponses

@ApiOperation(value = "Returns Authentication Result")
 @ApiResponses(value = { @ApiResponse(code = 200, message = "Successful Authentication") })

7. You can also run the testing for each API. Here is the final result I have done for a sample project:

Screenshot from 2018-04-27 10-41-10

Enjoy it and credit goes two these two links

https://github.com/TechPrimers/spring-boot-swagger-example

https://github.com/indrabasak/swagger-deepdive/wiki/Renaming-and-Sorting-REST-Controllers

Advertisements