springboot集成swagger3+swagger-bootstrap-ui及使⽤详解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.ller")) .paths(PathSelectors.any())
.build();
}
private ApiInfo builderApiInfo(){
return new ApiInfoBuilder()
.contact(
new Contact(
"系统名称",
"系统地址(www.baidu)",
"邮箱地址(123456@163)"
)
)
.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
如：localhost:8180/swagger-ui/index.html
bootstrap-ui 访问地址：地址/doc.html
如：localhost:8180/doc.html
5、使⽤详解
5.1 @Api
作⽤：在请求的类上添加该注解，表⽰对类的说明
参数：
tags=“说明该类的作⽤，可以在UI界⾯上看到的注解”value=“也是说明该类的作⽤，可⽤⽤tags代替”
⽰例：
@Api(value ="疾病管理")
@RestController
public class DiseaseController {
......
}
5.2 @ApiOperation
作⽤：在请求的⽅法上添加该注解，说明⽅法的⽤途、作⽤参数：
value=“说明⽅法的⽤途、作⽤”
notes=“⽅法的备注说明”
⽰例：
@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中，⼀般⽤于表达⼀个错误的响应信息
bootstrap项目参数：
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
⽰例：
@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)S
tring 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 常⽤的知识点到此为⽌。
版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。
发表评论