Configuring the Swagger2 interface documentation engine 45

Configuring the Swagger2 interface documentation engine 45

Configuring the Swagger2 interface documentation engine

Problems with handwritten documents

  • When a document needs to be updated, it needs to send another copy to the front end, that is, the document update communication is not timely.
  • Ambiguous interface return result
  • You can't test the interface directly online. You usually need to use tools, such as Postman
  • Too many interface documents, not easy to manage

Using Swagger to solve problems

Swagger is to solve this problem. Of course, it can't be said that swagger must be perfect. Of course, it has disadvantages. The most obvious is that the code is relatively implanted.


To increase the dependency required by Swagger2, pom.xml is configured as follows:

<!-- Swagger2 Begin -->
<!-- Swagger2 End -->

Configure Swagger2

Note: requesthandlerselectors.basepackage ("com. Full. Itoken. Service. Admin. Controller") is the controller package path, otherwise the generated document cannot scan the interface
That service needs to be created independently
Create a Java configuration class named Swagger2Config. The code is as follows:

package com.funtl.itoken.service.admin.config;

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

public class Swagger2Config {
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("iToken API File")
                .description("iToken API Gateway interface,")

Enable Swagger2

The annotation @ EnableSwagger2 in the Application indicates that Swagger is enabled

package com.funtl.itoken.service.admin;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import tk.mybatis.spring.annotation.MapperScan;

@SpringBootApplication(scanBasePackages = "com.funtl.itoken")
@MapperScan(basePackages = {"com.funtl.itoken.common.mapper", "com.funtl.itoken.service.admin.mapper"})
public class ServiceAdminApplication {
    public static void main(String[] args) {, args);

Using Swagger2

Add Swagger2 related notes to the Controller. The code is as follows:

 * Paging query
 * @param pageNum
 * @param pageSize
 * @param tbSysUserJson
 * @return
@ApiOperation(value = "Administrator paging query")
        @ApiImplicitParam(name = "pageNum", value = "Page number", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "pageSize", value = "Stroke number", required = true, dataType = "int", paramType = "path"),
        @ApiImplicitParam(name = "tbSysUserJson", value = "Administrator 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 tbSysUserJson
) throws Exception {

    TbSysUser tbSysUser = null;
    if (tbSysUserJson != null) {
        tbSysUser = MapperUtils.json2pojo(tbSysUserJson, TbSysUser.class);
    PageInfo pageInfo =, pageSize, tbSysUser);

    // Paged result set
    List<TbSysUser> list = pageInfo.getList();

    // Encapsulate Cursor object
    BaseResult.Cursor cursor = new BaseResult.Cursor();
    cursor.setTotal(new Long(pageInfo.getTotal()).intValue());

    return BaseResult.ok(list, cursor);

Swagger notes

Swagger annotates that the interface generates documents, including interface name, request method, parameter, return information, and so on.

  • @Api: decorate the whole class to describe the function of Controller
  • @ApiOperation: a method, or an interface, that describes a class
  • @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
  • @ApiImplicitParam: a request parameter
  • @Apiimplicit params: multiple request parameters

Visit Swagger2

Visit: http://ip:port/swagger-ui.html

Published 63 original articles, won praise 22, visited 6244
Private letter follow

Tags: Maven Spring JSON xml

Posted on Wed, 19 Feb 2020 23:49:16 -0500 by majik_sheff