SpringBoot集成Swagger

引入Swagger依赖

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>2.3.2.BUILD-SNAPSHOT</version>
    </dependency>
    <!-- Swagger相关依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

创建Swagger配置类

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage("com.xxx.controller"))
                .paths(PathSelectors.any())
                .build();
//        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }

    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact("xxx")
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

实体类信息

import com.anhk.annotation.ExcelField;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "用户信息")
public class User {
    /**
     * 姓名
     */
    @ApiModelProperty(value = "姓名")
    private String name;
    /**
     * 年龄
     */
    @ApiModelProperty(value = "年龄")
    private int age;
    /**
     * 性别
     */
    @ApiModelProperty(value = "性别")
    private String sex;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }

    public User() {
    }

    public User(String name, int age, String sex) {
        this.name = name;
        this.age = age;
        this.sex = sex;
    }

    @Override
    public String toString() {
        return "\"User\":{" + "\"name\":\"" + name + '\"' + ", \"age\":\"" + age + "\", \"sex\":\"" + sex + '\"' + "}";
    }
}

编写接口测试

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(description = "测试接口")
public class TestController extends AbstractController {


    @ApiOperation(value = "测试自定义异常接口")
    @GetMapping("/test")
    public ResponseEntity<User> testException(@RequestParam(name = "userName") @ApiParam(name = "userName", value = "用户姓名") String userName) {
        return ResponseEntity.ok(new User(userName, 18, "男"));
    }

    @ApiOperation(value = "测试第二个接口")
    @GetMapping("/test/two")
    public ResponseEntity<User> testInterface(@RequestParam(name = "userName") @ApiParam(name = "userName", value = "用户姓名") String userName,
                                              @RequestParam(name = "sex") @ApiParam(name = "sex", value = "性别") String sex) {
        return ResponseEntity.ok(new User(userName, 16, sex));
    }

    @ApiOperation(value = "新增用户")
    @PostMapping
    public ResponseEntity<User> testInterface(@RequestBody @ApiParam(name = "user", value = "用户信息") User user) {
        return ResponseEntity.ok(user);
    }
}

输入请求链接：http://ip:port/swagger-ui.html

swagger扫描多个包下的路径

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
 
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
 
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
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;
 
/**
 * Swagger2配置类
 * 
 * @author CL
 *
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
 
	/**
	 * 定义分隔符
	 */
	private static final String splitor = ";";
 
	/**
	 * 注入Docket
	 * 
	 * @return
	 */
	@Bean
	public Docket docket() {
		String basePackages = "com.c3stones.sys.controller" + splitor + "com.c3stones.common.controller";
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(basePackage(basePackages))
				.paths(PathSelectors.any()).build();
	}
 
	/**
	 * 声明基础包
	 * 
	 * @param basePackage 基础包路径
	 * @return
	 */
	public static Predicate<RequestHandler> basePackage(final String basePackage) {
		return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
	}
 
	/**
	 * 校验基础包
	 * 
	 * @param basePackage 基础包路径
	 * @return
	 */
	private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
		return input -> {
			for (String strPackage : basePackage.split(splitor)) {
				boolean isMatch = input.getPackage().getName().startsWith(strPackage);
				if (isMatch) {
					return true;
				}
			}
			return false;
		};
	}
 
	/**
	 * 检验基础包实例
	 * 
	 * @param requestHandler 请求处理类
	 * @return
	 */
	@SuppressWarnings("deprecation")
	private static Optional<? extends Class<?>> declaringClass(RequestHandler requestHandler) {
		return Optional.fromNullable(requestHandler.declaringClass());
	}
 
	/**
	 * 配置在线文档的基本信息
	 * 
	 * @return
	 */
	private static ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("SpringBoot集成Swagger2并配置多个包路径扫描示例")
				.contact(new Contact("Powered By C3Stones", "https://www.cnblogs.com/cao-lei", null))
				.termsOfServiceUrl("https://www.cnblogs.com/cao-lei/").version("V1.0").build();
	}

}