springboot集成swagger3+swagger-bootstrap-ui及使用详解

时间：2025-03-20 07:12:06

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((""))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo builderApiInfo() {
        return   new ApiInfoBuilder()
                .contact(
                        new Contact(
                                "系统名称",
                                "系统地址()",
                                "邮箱地址(123456@)"
                        )
                )
                .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/**",
                "/",
        };
        // 添加拦截器，配置拦截地址
        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 常用的知识点到此为止。

相关文章