接口文档总是很烦人,我曾经尝试过用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就能正常的渲染和访问了。
总结
今天分享了一些swagger3的配置心得,希望能够帮助你上手最新的swagger3文档工具。
本文转载自微信公众号「码农小胖哥」,可以通过以下二维码关注。转载本文请联系码农小胖哥公众号。