Swagger3.0 防踩坑使用指南

Swagger3.0 防踩坑指南

Swagger3.0基本使用和全局字段使用和拦截器问题处理

---

一、Swagger3.0

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API

1.所需包

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

二、基本使用

1.实例

//配置类需要注解 @EnableOpenApi @Configuration
@Bean
    public Docket createRestApi() {
        // 添加全局参数token令牌
        List<RequestParameter> requestParameter = new ArrayList<>();
        requestParameter.add(new RequestParameterBuilder()
                .name("token")
                .description("令牌")
                .required(false)
                .in(ParameterType.HEADER)
                .build());
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().globalRequestParameters(requestParameter);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口开发文档")
                .description("By ChuanDong Yang")
                .version("1.0")
                .contact(new Contact("船东阳", "http://localhost:99999",
                                "chuandongyanggg@163.com"))
                .build();
    }

2.拦截器配置

	public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
	}
    protected void addInterceptors(InterceptorRegistry registry) {
        try {
        	// 不拦截swagger3.0相关文件
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                            .excludePathPatterns("/swagger**/**")
                            .excludePathPatterns("/webjars/**")
                            .excludePathPatterns("/v3/**")
                            .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        super.addInterceptors(registry);
    }

注意：请求地址为http://localhost:port/swagger-ui/index.html 亲测有效!

---