赞
踩
<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>
@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() 是全局设置请求头参数,如不需要,则可以去掉。
@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); } }
Swagger 访问路径: 地址/swagger-ui/index.html
如:http://localhost:8180/swagger-ui/index.html
bootstrap-ui 访问地址:地址/doc.html
如:http://localhost:8180/doc.html
作用:在请求的类上添加该注解,表示对类的说明
参数:
tags=“说明该类的作用,可以在UI界面上看到的注解”
value=“也是说明该类的作用,可用用tags代替”
示例:
@Api(value = "疾病管理")
@RestController
public class DiseaseController {
......
}
作用:在请求的方法上添加该注解,说明方法的用途、作用
参数:
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));
}
作用:
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
注意 : 一般使用在GET请求中
参数:
@ApiImplicitParams 参数:@ApiImplicitParam
@ApiImplicitParam 参数:
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
示例如 5.2 所示。
作用:
@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)); }
作用:
@ApiModel:用于响应类上,表示一个返回响应数据的信息
@ApiModelProperty:用在属性上,描述响应类的属性
示例:
@ApiModel(value = "疾病详情实体")
@Data
public class DiseaseDetailDTO {
@ApiModelProperty("疾病id")
private String diseaseId;
@ApiModelProperty("疾病描述")
private String diseaseDesc;
@ApiModelProperty("疾病别名集合")
private List<DiseaseAliasNameDTO> aliasNameList;
}
至此,swagger 常用的知识点到此为止。
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。