springboot 集成swagger3

引入依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

配置

swagger配置，生产环境记得关闭swagger，节省性能。

@EnableOpenApi
@Configuration
public class SwaggerConfig {

    @Value("${swagger.enable}")
    private boolean enabel;

    @Value("${swagger.title}")
    private String titlte;

    @Value("${swagger.base-package}")
    private String basePackage;

    /**
     * 配置api
     * @return
     */
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
            .select()
            .apis(RequestHandlerSelectors.basePackage(basePackage))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(new ApiInfoBuilder().title(titlte).version("1.0").build())
            .enable(enabel)
            .securitySchemes(securitySchemes()).
            securityContexts(Arrays.asList(securityContexts()));
    }

    private List<SecurityScheme> securitySchemes() {
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        return Arrays.asList(apiKey);
    }

    private SecurityContext securityContexts() {
        return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.any())
            .build();
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("xxx", "描述信息");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("Authorization", authorizationScopes));
    }
}

#swagger配置
swagger:
  enable: true #是否开启swagger
  base-package: com.springboot.demo #要生成API文档的controller包路径
  title: springboot-demo #标题

security配置，主要是对swagger的相关请求不做拦截。

   @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        log.info("初始化自定义【securityFilterChain】配置");
        //禁用跨域防护
        http.csrf().disable();
        //禁用session
        http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
        //不拦截登录请求
        http.authorizeHttpRequests().antMatchers("/login/**").permitAll();
        //不拦截swagger相关请求
        http.authorizeHttpRequests().antMatchers("/swagger-ui/**","/swagger-resources/**","/v3/api-docs/**","/doc.html","/webjars/**").permitAll();
        //设置需要认证的api使用自定义的jwt身份验证管理器进行认证
        http.authorizeHttpRequests().anyRequest().access(jwtAuthorizationManager);
        return http.build();
    }

如果启动时发生报以下错误，修改springboot的url匹配规则配置

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

测试

        应用启动后，在浏览器访问http://localhost:8080/swagger-ui/index.html

界面美化

        引入依赖，重启应用，访问：http://localhost:8080/doc.html

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-ui</artifactId>
            <version>3.0.3</version>
        </dependency>

在下图位置添加全局授权，会在所有请求的header上自动加上所填参数

 常用注解

@Api(tags = {"tag1","tag2","..."})

@ApiOperation(value = "功能描述",notes = "备注")

@ApiModel(value="类名",description="类描述")

@ApiModelProperty(value = "类属性描述",required = *true*,example = "属性举例",notes = "备注")

@ApiImplicitParams({@ApiImplicitParam(),@ApiImplicitParam(),...})

@ApiImplicitParam(name = "参数名",value = "参数描述",required = *true*,paramType = "接口传参类型",dataType = "参数数据类型")

@ApiResponses({ @ApiResponse(),@ApiResponse(),..})

@ApiResponse(code = 10001, message = "返回信息")

@ApiIgnore：忽略注解（在swagger界面不显示该字段）