美文网首页
Springboot整合springfox3+knife4j,生

Springboot整合springfox3+knife4j,生

作者: alex很累 | 来源:发表于2022-02-18 10:45 被阅读0次

    一、概述

    在这篇博客中,会记录springfox3的基本配置与使用;由于swagger-ui看得不是很习惯,额外引入了knife4j,使用增强版本的swagger的前端ui。

    二、依赖

    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    <dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>knife4j-spring-ui</artifactId>
        <version>3.0.3</version>
    </dependency>
    

    三、swagger的配置和使用

    1.在这里不使用注解@EnableOpenApi。

    2.Swagger3Config.java进行配置

    @Configuration
    @ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
    public class Swagger3Config {
        @Bean
        public Docket createRestApi() {
            // 添加token参数
            RequestParameterBuilder requestParameterBuilder = new RequestParameterBuilder()
                    .name("token")
                    .description("token")
                    .in(ParameterType.HEADER)
                    // 类内部创建了默认的builder以供属性设置
                    .query(parameterSpecificationBuilder -> parameterSpecificationBuilder.defaultValue("1")
                            .allowEmptyValue(true));
            return new Docket(DocumentationType.OAS_30)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                    .paths(PathSelectors.any())
                    .build()
                    .globalRequestParameters(Lists.newArrayList(requestParameterBuilder.build()));
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("xxxxxxxxxxxxxx")
    //                .description("springboot | swagger")
    //                .contact(new Contact("", "", ""))
    //                .version("1.0.0")
                    .build();
        }
    }
    

    注意
    @ConditionalOnProperty注解声明了当springfox.documentation.enabledtrue时启用配置,而且默认值就是true(Swagger仅仅建议在开发阶段使用);

    3.对一些内置接口的访问放行

    这里以WebMvcConfig为例。

    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(loginInterceptor).addPathPatterns("/**")
                .excludePathPatterns("/login")
                .excludePathPatterns("/js/**")
                .excludePathPatterns("/css/**")
                .excludePathPatterns("/image/**")
                .excludePathPatterns("/uploads/**")
                // swagger
                .excludePathPatterns("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/v3/**", "/swagger-ui.html/**")
                // knife4j
                .excludePathPatterns("/doc.html", "/doc.html/**");
        registry.addInterceptor(sqlInjectInterceptor).addPathPatterns("/**");
    }
    

    4.基本使用

    Swagger2注解 简单说明
    @Api(tags = "xxx模块说明") 作用在模块类上
    @ApiOperation("xxx接口说明") 作用在接口方法上
    @ApiModel("xxxPOJO说明") 作用在模型类上:如VO、BO
    @ApiModelProperty(value = "xxx属性说明",hidden = true) 作用在类方法和属性上,hidden设置为true可以隐藏该属性
    @ApiParam("xxx参数说明") 作用在方法的参数上
    @ApiImplicitParams 用在请求的方法上,表示一组参数说明

    @ApiImplicitParam
    用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
    name:参数名
    value:参数的汉字说明、解释
    required:参数是否必须传
    paramType:参数放在哪个地方
    · header --> 请求参数的获取:@RequestHeader
    · query --> 请求参数的获取:@RequestParam
    · path(用于restful接口)--> 请求参数的获取:@PathVariable
    · body(不常用)
    · form(不常用)
    dataType:参数类型,默认String,其它值dataType="Integer"
    defaultValue:参数的默认值

    四、登录页面查看接口文档

    swagger页面:项目地址 + /swagger-ui/index.html
    knife4j页面:项目地址 + /doc.html

    五、遇到的问题

    1. swagger3中,设置全局参数不生效

    github

    六、参考资料

    1. Swagger3就是比2简单粗暴
    2. 上手Swagger3.0,踩了两个坑
    3. swagger2 注解说明
    4. OpenApi3/Swagger3简单使用及与swagger2对比

    相关文章

      网友评论

          本文标题:Springboot整合springfox3+knife4j,生

          本文链接:https://www.haomeiwen.com/subject/afjelrtx.html