一、概述

在这篇博客中，会记录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.enabled为true时启用配置，而且默认值就是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.基本使用

@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对比