Swagger3就是比2简单粗暴

接口文档总是很烦人，我曾经尝试过用Postman来编写和分享项目文档，感觉还不错。但是最近项目紧，我没有额外的时间可以花在它上面，这也导致我尝试YApi（另外一种文档）的计划泡汤了。嗯，目...

码农小胖哥

3461人浏览 · 2021-04-13 07:30:00

码农小胖哥 · 2021-04-13 07:30:00 发布

接口文档总是很烦人，我曾经尝试过用Postman来编写和分享项目文档，感觉还不错。但是最近项目紧，我没有额外的时间可以花在它上面，这也导致我尝试YApi（另外一种文档）的计划泡汤了。嗯，目前没有比Swagger更快、更傻瓜的工具，虽然它有严重的代码污染。先拿这个对付一阵时间，等闲暇时间再玩YApi。

Swagger3集成

Swagger目前最新版本是3.0.0,在Spring Boot应用中集成Swagger3比老的Swagger2简单多了，它提供了一个Starter组件。

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

就这就可以了，简单不？

至于有的教程说还要开启注解@EnableOpenApi，完全不需要。因为在springfox-boot-starter-3.0.0.jar下你可以找到一个spring.factories，熟悉Spring Boot的同学都知道这个是一个Spring Boot 特有的SPI文件，能够自动的发现并注册Starter组件的配置。里面有这样的配置：

# Auto Configure
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
springfox.boot.starter.autoconfigure.OpenApiAutoConfiguration

顺藤摸瓜，找到总的配置类OpenApiAutoConfiguration：

@Configuration
@EnableConfigurationProperties(SpringfoxConfigurationProperties.class)
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
@Import({
    OpenApiDocumentationConfiguration.class,
    SpringDataRestConfiguration.class,
    BeanValidatorPluginsConfiguration.class,
    Swagger2DocumentationConfiguration.class,
    SwaggerUiWebFluxConfiguration.class,
    SwaggerUiWebMvcConfiguration.class
})
@AutoConfigureAfter({ WebMvcAutoConfiguration.class, JacksonAutoConfiguration.class,
    HttpMessageConvertersAutoConfiguration.class, RepositoryRestMvcAutoConfiguration.class })
public class OpenApiAutoConfiguration {

}

一些发现

我们找到了关键的一个地方@ConditionalOnProperty注解声明了当springfox.documentation.enabled为true时启用配置，而且默认值就是true。这非常有用，Swagger仅仅建议在开发阶段使用，这个正好是个开关。另外有时候我们自定义配置的时候最好把这个开关也加上：

// 自定义swagger3文档信息
@Configuration
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("更多请咨询felord.cn")
                .contact(new Contact("码农小胖哥", "https://felord.cn", "dax@felord.cn"))
                .version("1.0.0")
                .build();
    }
}

❝
如果你想在Swagger3中加入Json Web Token，可以参考这篇文章。

最开始我们提到Swagger3不需要使用@EnableOpenApi或者@EnableSwagger2开启，这里也能找到答案。

@Import(OpenApiDocumentationConfiguration.class)
public @interface EnableOpenApi {
}

@Import(Swagger2DocumentationConfiguration.class)
public @interface EnableSwagger2 {
}

上面的两个导入类都可以在OpenApiAutoConfiguration找到，所以Swagger3提供的是全自动的集成。

和全局统一参数不兼容

如果你使用了统一返回体封装器来标准化Spring MVC接口的统一返回

/**
 * 返回体统一封装器
 *
 * @author n1
 */
@RestControllerAdvice 
public class RestBodyAdvice implements ResponseBodyAdvice<Object> {
    @Override
    public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
        return !returnType.hasMethodAnnotation(IgnoreRestBody.class);
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {

        if (body == null) {
            return RestBody.ok();
        }
        if (Rest.class.isAssignableFrom(body.getClass())) {
            return body;
        }
        return RestBody.okData(body);
    }
}

你会发现Swagger3会报Unable to infer base url……的错误，这是因为统一返回体影响到了Swagger3的一些内置接口。解决方法是@RestControllerAdvice控制好生效的包范围,也就是配置其basePackages参数就行了，这个潜在的冲突浪费我了一个多小时。

安全框架放行

如果你使用安全框架，Swagger3的内置接口就会访问受限，我们需要排除掉。Spring Security是这么配置的：

@Override
public void configure(WebSecurity web) throws Exception {
    //忽略swagger3所需要用到的静态资源，允许访问
    web.ignoring().antMatchers( "/swagger-ui.html",
            "/swagger-ui/**",
            "/swagger-resources/**",
            "/v2/api-docs",
            "/v3/api-docs",
            "/webjars/**");
}

如果你使用的版本是Spring Security 5.4，你可以这么定制WebSecurity:

@Bean
WebSecurityCustomizer swaggerWebSecurityCustomizer() {
    return (web) -> {
        web.ignoring().antMatchers(new String[]{"/swagger-ui.html", "/swagger-ui/**", "/swagger-resources/**", "/v2/api-docs", "/v3/api-docs", "/webjars/**"});
    };
}

更加方便简单，这样Swagger就能正常的渲染和访问了。