新建spring boot项目，并添加swagger相关依赖，完整pom如下：
4.0.0
org.springframework.boot
spring-boot-starter-parent
2.4.2
com.example
boot-swagger
0.0.1-SNAPSHOT
boot-swagger
Demo project for Spring Boot
1.8
org.springframework.boot
spring-boot-starter-web
org.projectlombok
lombok
true
org.springframework.boot
spring-boot-starter-test
test
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
com.github.xiaoymin
swagger-bootstrap-ui
1.9.6
org.springframework.data
spring-data-commons
org.springframework.boot
spring-boot-maven-plugin
org.projectlombok
lombok
新建swagger配置类
package com.example.bootswagger.config;
import com.fasterxml.classmate.TypeResolver;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Getter;
import lombok.Setter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.data.domain.Pageable;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.AlternateTypeRule;
import springfox.documentation.schema.AlternateTypeRuleConvention;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* @author liujy
* @description swagger配置类
* @since 2021-01-18 09:54
*/
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Configuration
class SwaggerBootstrapUIConfiguration {
public static final String basePackage = "com.example.bootswagger";
public static final String title = "spring boot整合swagger";
public static final String des = "spring boot整合swagger";
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 设置包扫描路径
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build();
}
@Bean
public Docket createWebApi() {
// 创建 Docket 对象
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.ant("/**/w/**"))
.build().groupName("Web端API接口文档");
return docket;
}
@Bean
public Docket createMobileApi() {
// 创建 Docket 对象
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.ant("/**/m/**"))
.build().groupName("Mobile端API接口文档");
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(des)
.version("1.0")
.build();
}
/**
* 将Pageable转换展示在swagger中
*/
@Bean
public AlternateTypeRuleConvention pageableConvention(final TypeResolver resolver) {
return new AlternateTypeRuleConvention() {
@Override
public int getOrder() {
return Ordered.HIGHEST_PRECEDENCE;
}
@Override
public List rules() {
List list = new ArrayList<>();
list.add(new AlternateTypeRule(resolver.resolve(Pageable.class), resolver.resolve(Page.class)));
return list;
}
};
}
@ApiModel
@Getter
@Setter
private class Page {
@ApiModelProperty(value = "请求分页页码 (0..N)", example = "0")
private Integer page = 0;
@ApiModelProperty(value = "每页的记录数", example = "10")
private Integer size = 10;
@ApiModelProperty(value = "排序格式: property(,asc|desc). 默认是升序 asc. 支持多个排序条件", example = "createdDate,desc")
private List sort;
}
}
controller测试类
package com.example.bootswagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.web.PageableDefault;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author liujy
* @description web测试接口
* @since 2021-01-18 10:05
*/
@RestController
// 匹配swagger配置类中**/w/**的path配置
@RequestMapping(value = "/web/w")
@Api(tags = {"测试模块-测试控制器"})
public class TestWebController {
@ApiOperation("这是一个web接口")
@GetMapping("/t1")
public String test(@PageableDefault(value = 10, sort = {"createDate"}, direction = Sort.Direction.DESC) final Pageable pageable) {
return "web interface success";
}
}
package com.example.bootswagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author liujy
* @description mobile测试接口
* @since 2021-01-18 11:31
*/
@RestController
// 匹配swagger配置类中**/w/**的path配置
@RequestMapping(value = "/app/m")
@Api(tags = {"测试模块-测试控制器"})
public class TestAppController {
@ApiOperation("这是一个mobile接口")
@GetMapping("/t1")
public String test() {
return "mobile interface success";
}
}
项目包结构如图：
项目包结构
启动项目，访问http://ip:port/doc.html或者http://ip:port/swagger-ui.html（注意：http://ip:port/swagger-ui.html可用来测试文件下载）
访问http://ip:port/swagger-ui.html
访问http://ip:port/doc.html
如图，web测试接口中所需的page信息也已经生效：
page信息