Introducing dependency

Add io.springfox:springfox-swagger2 and io.springfox:springfox-swagger-ui dependencies to pom.xml

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>

Related configuration

Create Swagger2Config configuration class

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("{Controler Scan path}"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("{Title}")
                .description("{describe}")
                .termsOfServiceUrl("{Website}")
                .version("{Version number}")
                .build();
    }
}

Add @ EnableSwagger2 annotation in Application

@EnableSwagger2
@SpringBootApplication
public class ServiceAdminApplication {
    public static void main(String[] args) {
        SpringApplication.run(ServiceAdminApplication.class, args);
    }
}

Using Swagger2

Add the following common Swagger notes to the request interface in the Controller

@RestController
@RequestMapping(value = "/api/v2/user")
@Api(tags = "user management")
public class UserController() {

	@ApiOperation(value = "Paging query user list")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "pageNum", value = "Page number", required = true, dataType = "int", paramType = "path"),
			@ApiImplicitParam(name = "pageSize", value = "The number of pages", required = true, dataType = "int", paramType = "path"),
			@ApiImplicitParam(name = "UserJson", value = "object JSON Character string", required = false, dataTypeClass = String.class, paramType = "json")
	})
	@RequestMapping(value = "page/{pageNum}/{pageSize}", method = RequestMethod.GET)
	public BaseResult page(
		@PathVariable(required = true) int pageNum, 
		@PathVariable(required = true) int pageSize,
		@RequestParam(required = false) String UserJson
	){
		return null;
	}
}

Instructions for using Swagger annotation

• @Api: decorate the whole class to describe the function of Controller
• @ApiOperation: a method, or an interface, that describes a class
• @ApiImplicitParam: a request parameter
• @Apiimplicit params: multiple request parameters
• @ApiParam: single parameter description
• @ApiModel: receiving parameters with objects
• @ApiProperty: a field describing an object when receiving parameters with the object
• @ApiResponse: HTTP response one of the descriptions
• @ApiResponses: overall description of HTTP response
• @ApiIgnore: use this annotation to ignore this API
• @ApiError: information returned when an error occurs

To start the project, visit the Swagger address: http://{ip}:{port}/swagger-ui.html

• Author: Peng Chao
• This article starts from personal blog: https://antoniopeng.com/2019/07/28/springboot/SpringBoot%E9%9B%86%E6%88%90Swagger2%E6%9E%84%E5%BB%BARESTfulAPI%E6%96%87%E6%A1%A3/
• Copyright notice: except for the special notice, all articles in this blog adopt CC BY-NC-SA 4.0 license agreement. Reprint please indicate from Peng Chao's Blog!