百度360必应搜狗淘宝本站头条
当前位置:网站首页 > 技术分类 > 正文

比试一下:Swagger3就是比2简单粗暴

ztj100 2024-12-15 18:01 22 浏览 0 评论

作者:码农小胖哥 来源:码农小胖哥

接口文档总是很烦人,我曾经尝试过用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会报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文档工具。

相关推荐

Sublime Text 4 稳定版 Build 4113 发布

IT之家7月18日消息知名编辑器SublimeText4近日发布了Build4113版本,是SublimeText4的第二个稳定版。IT之家了解到,SublimeTe...

【小白课程】openKylin便签贴的设计与实现

openKylin便签贴作为侧边栏的一个小插件,提供便捷的文本记录和灵活的页面展示。openKylin便签贴分为两个部分:便签列表...

“告别 Neovim!为什么我投奔了刚开源的 Zed 编辑器?”

...

壹啦罐罐 Android 手机里的 Xposed 都装了啥

这是少数派推出的系列专题,叫做「我的手机里都装了啥」。这个系列将邀请到不同的玩家,从他们各自的角度介绍手机中最爱的或是日常使用最频繁的App。文章将以「每周一篇」的频率更新,内容范围会包括iOS、...

电气自动化专业词汇中英文对照表(电气自动化专业英语单词)

专业词汇中英文对照表...

Python界面设计Tkinter模块的核心组件

我们使用一个模块,我们要熟悉这个模块的主要元件。如我们设计一个窗口,我们可以用Tk()来完成创建;一些交互元素,按钮、标签、编辑框用到控件;怎么去布局你的界面,我们可以用到pack()、grid()...

以色列发现“死海古卷”新残片(死海古卷是真的吗)

编译|陈家琦据艺术新闻网(artnews.com)报道,3月16日,以色列考古学家发现了死海古卷(DeadSeaScrolls)新残片。新出土的羊皮纸残片中包括以希腊文书写的《十二先知书》段落,这...

鸿蒙Next仓颉语言开发实战教程:订单列表

大家上午好,最近不断有友友反馈仓颉语言和ArkTs很像,所以要注意不要混淆。今天要分享的是仓颉语言开发商城应用的订单列表页。首先来分析一下这个页面,它分为三大部分,分别是导航栏、订单类型和订单列表部分...

哪些模块可以用在 Xposed for Lollipop 上?Xposed 模块兼容性解答

虽然已经有了XposedforLollipop的安装教程,但由于其还处在alpha阶段,一些Xposed模块能不能依赖其正常工作还未可知。为了解决大家对于模块兼容性的疑惑,笔者尽可能多...

利用 Fluid 自制 Mac 版 Overcast 应用

我喜爱收听播客,健身、上/下班途中,工作中,甚至是忙着做家务时。大多数情况下我会用MarcoArment开发的Overcast(Freemium)在iPhone上收听,这是我目前最喜爱的Po...

Avalonia日志组件实现与优化指南(ar日志表扣)

...

浅色Al云食堂APP代码(三)(手机云食堂)

以下是进一步优化完善后的浅色AI云食堂APP完整代码,新增了数据可视化、用户反馈、智能推荐等功能,并优化了代码结构和性能。项目结构...

实战PyQt5: 121-使用QImage实现一个看图应用

QImage简介QImage类提供了独立于硬件的图像表示形式,该图像表示形式可以直接访问像素数据,并且可以用作绘制设备。QImage是QPaintDevice子类,因此可以使用QPainter直接在图...

滚动条隐藏及美化(滚动条隐藏但是可以滚动)

1、滚动条隐藏背景/场景:在移动端,滑动的时候,会显示默认滚动条,如图1://隐藏代码:/*隐藏滚轮*/.ul-scrool-box::-webkit-scrollbar,.ul-scrool...

浅色AI云食堂APP完整代码(二)(ai 食堂)

以下是整合后的浅色AI云食堂APP完整代码,包含后端核心功能、前端界面以及优化增强功能。项目采用Django框架开发,支持库存管理、订单处理、财务管理等核心功能,并包含库存预警、数据导出、权限管理等增...

取消回复欢迎 发表评论: