1、引入 maven 依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
2、配置 swagger
@EnableOpenApi
@Configuration
public class Swagger3Config {
@Bean
public Docket docket() {
return new Docket(DocumentationType.OAS_30)
.securityContexts(securityContexts())
.securitySchemes(securitySchemes())
.apiInfo(builderApiInfo())
.select()
// 扫描所有带有 @ApiOperation 注解的类
.apis( RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描所有的 controller
// .apis(RequestHandlerSelectors.basePackage("com.shenlanbao.product.library.management.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo builderApiInfo() {
return new ApiInfoBuilder()
.contact(
new Contact(
"系统名称",
"系统地址(https://www.baidu.com)",
"邮箱地址(123456@163.com)"
)
)
.title("xxx项目接口文档")
.description("xxxx项目接口文档")
.version("1.0")
.build();
}
/**
* 配置请求头 token
*/
private List<SecurityContext> securityContexts(){
return Arrays.asList(SecurityContext.builder()
.securityReferences(Arrays.asList(SecurityReference.builder()
.reference("token")
.scopes(new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")})
.build())).build());
}
/**
* 配置请求头 token 参数
*/
private List<SecurityScheme> securitySchemes(){
return Arrays.asList(new ApiKey("token凭证", "token", "header"));
}
}
其中 securityContexts() 与 securitySchemes() 是全局设置请求头参数，如不需要，则可以去掉。
3、拦截器放行（如没有拦截器，此步骤可忽略）
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Autowired
private AuthInterceptor addPathPatterns;
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 排除 swagger 访问的路径配置
String[] swaggerExcludes = new String[]{
"/swagger-ui/**",
"/swagger-resources/**",
"/webjars/**",
"/v3/**",
"/doc.html",
};
// 添加拦截器，配置拦截地址
registry.addInterceptor(addPathPatterns)
.addPathPatterns("/**")
.excludePathPatterns(swaggerExcludes);
}
}
4、访问
Swagger 访问路径： 地址/swagger-ui/index.html
如：http://localhost:8180/swagger-ui/index.html
bootstrap-ui 访问地址：地址/doc.html
如：http://localhost:8180/doc.html
5、使用详解
5.1 @Api
作用：在请求的类上添加该注解，表示对类的说明
参数：
tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“也是说明该类的作用，可用用tags代替”
示例：
@Api(value = "疾病管理")
@RestController
public class DiseaseController {
......
}
5.2 @ApiOperation
作用：在请求的方法上添加该注解，说明方法的用途、作用
参数：
value=“说明方法的用途、作用”
notes=“方法的备注说明”
示例：
@ApiOperation(value = "疾病列表（包含疾病程度）")
@ApiImplicitParams({
@ApiImplicitParam(name = "labelId",value = "疾病标签ID",dataType = "String",paramType = "query",required = false),
@ApiImplicitParam(name = "diseaseStatus",value = "疾病状态",dataType = "String",paramType = "query",required = false),
@ApiImplicitParam(name = "intelligentUnderwritingId",value = "智能核保ID",dataType = "String",paramType = "query",required = false)
})
@GetMapping
public Result<List<DiseaseListVO>> diseaseListAndLevel(@RequestParam(value = "labelId",required = false)String labelId,
@RequestParam(value = "diseaseStatus",required = false) String diseaseStatus,
@RequestParam(value = "intelligentUnderwritingId",required = false) String intelligentUnderwritingId) {
return ResultUtils.success(tbDiseaseService.selectListAndLevel(labelId,diseaseStatus,intelligentUnderwritingId));
}
5.3 @ApiImplicitParams 与 @ApiImplicitParam
作用：
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
注意 ： 一般使用在GET请求中
参数：
@ApiImplicitParams 参数：@ApiImplicitParam
@ApiImplicitParam 参数：
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
- header --> 请求参数的获取：@RequestHeader
- query --> 请求参数的获取：@RequestParam
- path（用于restful接口）–> 请求参数的获取：@PathVariable
- div（不常用）
- form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值
示例如 5.2 所示。
5.4 @ApiResponses 与 @ApiResponse (一般情况无需设置)
作用：
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
参数：
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
示例：
@ApiOperation(value = "疾病列表（无疾病程度）")
@ApiImplicitParams({
@ApiImplicitParam(name = "labelId",value = "疾病标签ID",dataType = "String",paramType = "query",required = false),
@ApiImplicitParam(name = "diseaseStatus",value = "疾病状态",dataType = "String",paramType = "query",required = false),
@ApiImplicitParam(name = "intelligentUnderwritingId",value = "智能核保ID",dataType = "String",paramType = "query",required = false)
})
@ApiResponses(
{
@ApiResponse(code = 400,message = "请求失败"),
@ApiResponse(code = 200,message = "请求成功"),
}
)
@GetMapping("/list")
public Result<List<DiseaseListVO>> diseaseList(@RequestParam(value = "labelId",required = false)String labelId,
@RequestParam(value = "diseaseStatus",required = false) String diseaseStatus,
@RequestParam(value = "intelligentUnderwritingId",required = false) String intelligentUnderwritingId) {
return ResultUtils.success(tbDiseaseService.selectList(labelId,diseaseStatus,intelligentUnderwritingId));
}
5.5 @ApiModel 与 @ApiModelProperty
作用：
@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性
示例：
@ApiModel(value = "疾病详情实体")
@Data
public class DiseaseDetailDTO {
@ApiModelProperty("疾病id")
private String diseaseId;
@ApiModelProperty("疾病描述")
private String diseaseDesc;
@ApiModelProperty("疾病别名集合")
private List<DiseaseAliasNameDTO> aliasNameList;
}
至此，swagger 常用的知识点到此为止。
