Swagger-v2 & v3 说明配置
注意
spring-boot 版本 >= 2.6.x 的 swagger 配置请看这里: 🐱🚀
一、注解说明
Swagger 使用的注解及其说明:
作用于-Controller类
@Api
@Api:用在类上,说明该类的作用。
@Api(value = "代码生成", tags = "代码生成") public class TestController{}
作用于-方法
@ApiOperation:给方法增加说明。
@ApiOperation(value = "获取用户列表", notes = "获取用户列表") public R userList() {}
value:显示在 Controller 里面
tags:显示在 Controller 外部
@ApiOperation(value = "添加学生", tags = "添加学生") @ApiOperation(value = "删除学生", tags = "删除学生") @ApiOperation(value = "获取学生list") @ApiOperation(value = "获取学生by ID")
@RequestBody 接收对象传参
@PostMapping("/add")
@ResponseStatus(HttpStatus.CREATED)
@ApiOperation(value = "新增用户", notes = "新增用户")
public void addUser(@RequestBody User user) {
logger.info("LandLord DTO is: "+user);
}
@ApiImplicitParam:给方法参数增加说明。
@ApiOperation(value = "获取用户详细", notes = "获取用户详细") @ApiImplicitParam(name = "userId", value = "用户ID", required = true, paramType = "path", dataType = "Integer", dataTypeClass = Integer.class) public R getUser(@PathVariable Integer userId) {}
参数 说明 name: String 参数名 value: String 参数说明&描述 defaultValue: String 参数的默认值 required: boolean 参数是否必须传 dataType: String 参数类型 paramType: String 指定参数放在哪个地方。
header:请求参数放置于RequestHeader,使用 @RequestHeader 获取
query:请求参数放置于请求地址,使用 @RequestParam 获取
path:(用于 restful 接口)使用 @PathVariable 获取
body:(不常用)
form(不常用)
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParams({ @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "test"), @ApiImplicitParam(paramType = "query", name = "password", value = "密码", required = true, defaultValue = "123") }) @PostMapping("/user") public String addUser(@RequestParam String username, @RequestParam String password) { return "新增用户:" + username + " " + password; }
接收 参数&对象组合
@ApiOperation(value="修改医生信息", notes="")
@ApiImplicitParam(paramType="query", name = "doctorId", value = "医生ID", required = true, dataType = "Integer")
public String updateDoctor(@RequestParam Integer doctorId, @RequestBody DemoDoctor doctor){}
接收 参数&header组合
@ApiImplicitParams({
@ApiImplicitParam(paramType="header", name = "token", value = "token", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query", name = "pageIndex", value = "当前页数", required = false, dataType = "String"),
@ApiImplicitParam(paramType="query", name = "pageSize", value = "每页记录数", required = true, dataType = "String"),
})
public PageInfo<DemoDoctor> getDoctorList(@RequestParam(value = "pageIndex", required = false, defaultValue = "1") Integer pageIndex,
@RequestParam(value = "pageSize", required = false) Integer pageSize,
HttpServletRequest request){}
@ApiResponses:用于表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiOperation(value = "删除用户", notes = "根据 id 删除用户") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path", dataTypeClass = Integer.class) @ApiResponses({ @ApiResponse(code = 200, message = "删除成功!"), @ApiResponse(code = 500, message = "删除失败!") }) public R delete(@PathVariable Integer id) {}
注意:
在@RequestMapper中必须指定RequestMethod的类型,否则Sawgger会默认为全类型皆可访问, API列表中会生成多条项目。
作用于-实体类
@ApiModel:描述一个Model的信息
(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModel(value = "UserEntity", description = "用户实体") public class UserEntity {}
@ApiModelProperty:描述一个model的属性
@ApiModelProperty(value = "用户ID") private Integer userId;
二、swagger2 配置
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<exclusions>
<exclusion>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
</exclusion>
</exclusions>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.google.guava</groupId>
<artifactId>guava</artifactId>
<version>25.1-jre</version>
</dependency>
/**
* Swagger2 的接口配置
*
* @author jf
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {
/**
* 系统基础配置
*/
@Autowired
private ModelConfig modelConfig;
/**
* 是否开启swagger
*/
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 设置请求的统一前缀
*/
@Value("${swagger.pathMapping}")
private String pathMapping;
/**
* 分组:sys管理
*
* @return Docket
*/
@Bean
public Docket sys_api_app() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(enabled)
.apiInfo(apiInfo("标题:学生管理_API", "学生"))
.select()
.apis(RequestHandlerSelectors.basePackage("cn.springboot.model.web.controller"))
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// .apis(RequestHandlerSelectors.any())
// .paths(PathSelectors.any())
.paths(PathSelectors.ant("/stu/**"))
.build()
.groupName("学生")
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping(pathMapping);
}
@Bean
public Docket clas_api_app() {
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(enabled)
.apiInfo(apiInfo("标题:班级管理_API", "班级"))
.select()
.apis(RequestHandlerSelectors.basePackage("cn.springboot.model.web.controller"))
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// .apis(RequestHandlerSelectors.any())
// .paths(PathSelectors.any())
.paths(PathSelectors.ant("/class/**"))
.build()
.groupName("班级")
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping(pathMapping);
}
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(o -> o.matches("/.*"))
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 构建api文档的详细信息
*
* @param title 标题
* @param description 描述
* @return ApiInfo
*/
private ApiInfo apiInfo(String title, String description) {
return new ApiInfoBuilder()
.title(title)
.description(description)
// 作者信息
.contact(new Contact(modelConfig.getName(), null, null))
.version("版本号:" + modelConfig.getVersion())
.build();
}
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
registry.addResourceHandler("/static/**")
.addResourceLocations(ResourceUtils.CLASSPATH_URL_PREFIX + "/static/");
WebMvcConfigurer.super.addResourceHandlers(registry);
}
}
三、swagger3 配置
<!-- Swagger3依赖 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.6.2</version>
</dependency>
/**
* Swagger 的接口配置
*
*/
@Configuration
public class SwaggerConfig {
@Value("${project.name}")
private String name;
@Value("${project.version}")
private String version;
/**
* 是否开启swagger
*/
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 设置请求的统一前缀
*/
@Value("${swagger.pathMapping}")
private String pathMapping;
/**
* 分组:sys管理
*
* @return Docket
*/
@Bean
public Docket sys_api_app() {
return new Docket(DocumentationType.OAS_30)
// 是否启用Swagger
.enable(enabled)
// 用来创建该API的基本信息,展示在文档的页面中(自定义展示的信息)
.apiInfo(apiInfo("标题:系统管理模块_API", "system"))
// 设置哪些接口暴露给Swagger展示
.select()
/扫描
.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.system.controller"))
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// .apis(RequestHandlerSelectors.any())
/请求路径
//.paths(PathSelectors.any())
.paths(PathSelectors.ant("/system/**"))
.build()
/设置安全模式,swagger可以设置访问token
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.groupName("system")
.pathMapping(pathMapping);
}
/**
* 分组: tool 管理
*
* @return Docket
*/
@Bean
public Docket tool_api_app() {
return new Docket(DocumentationType.OAS_30)
.enable(enabled)
.apiInfo(apiInfo("标题:系统工具模块_API", "tool"))
.select()
.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.gen.controller"))
.paths(PathSelectors.ant("/tool/**"))
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.groupName("tool")
.pathMapping(pathMapping + "/tool");
}
/**
* 安全模式,这里指定token通过Authorization头请求头传递
*/
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
/**
* 安全上下文
*/
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.operationSelector(o -> o.requestMappingPattern().matches("/.*"))
.build());
return securityContexts;
}
/**
* 默认的安全上引用
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
/**
* 构建api文档的详细信息
*
* @param title 标题
* @param description 描述
* @return ApiInfo
*/
private ApiInfo apiInfo(String title, String description) {
return new ApiInfoBuilder()
.title(title)
.description(description)
// 作者信息
.contact(new Contact(name, null, null))
.version("版本号:" + version)
.build();
}
}
四、使用 swagger-bootstrap-ui
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
Swagger 文档: http://192.168.56.1:51156/dev/doc.html