Swagger 的作用与使用详解

最新推荐文章于 2025-06-13 09:45:15 发布

大雄编程

最新推荐文章于 2025-06-13 09:45:15 发布

阅读量9.8k

点赞数 4

CC 4.0 BY-SA版权

文章标签： java 开发语言

本文链接：https://blog.csdn.net/xiaoxiong092620/article/details/125869398

Swagger是一个用于生成、描述和交互式测试RESTful API的框架。它能帮助开发者在代码中通过注解创建接口文档，实现接口文档与代码的同步更新，避免文档过时的问题。Swagger的优点包括在线生成接口文档、支持接口测试和多语言，简化了前后端分离项目的接口管理。集成Swagger的步骤包括添加依赖、配置WebMvcConfig、设置静态资源映射以及在拦截器中排除特定路径。常用的Swagger注解如@Api、@ApiOperation等用于详细描述接口及其操作。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

文章目录

前言
一、Swagger 的作用
二、Swagger 的优点
三、使用步骤
- 1.导入 knife4j的maven坐标
- 2.导入knife4j相关配置（WebMvcConfig）
- 3.设置静态资源映射
- 4.在拦截器中设置不需要处理的请求路径
四、Swagger 常用注解
总结

前言

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务的接口文档。

目前的项目基本都是前后端分离，后端为前端提供接口的同时，还需同时提供接口的说明文档。但我们的代码总是会根据实际情况来实时更新，这个时候有可能会忘记更新接口的说明文档，造成一些不必要的问题。

一、Swagger 的作用

根据在代码中使用自定义的注解来生成接口文档，这个在前后端分离的项目中很重要。这样做的好处是在开发接口时可以通过swagger 将接口文档定义好，同时也方便以后的维护。

在没有swagger之前，我们可以使用word，excel等功能来书写接口定义文档，但又有一个弊端，即：在接口发送改变时需要及时的同步接口文档，否则实际的接口与接口文档不相符，则接口文件就失去了作用，甚至会起到反作用。

二、Swagger 的优点

号称时最流行的 API 框架

接口文档在线生成，避免同步的麻烦

可以支持在线对接口执行测试

支持多语言

三、使用步骤

1.导入 knife4j的maven坐标

 <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

2.导入knife4j相关配置（WebMvcConfig）

3.设置静态资源映射

设置静态资源映射(WebMvcConfig类中的addResourceHandlers方法) ,否则接口文档页面无法访问

 registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
 registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

4.在拦截器中设置不需要处理的请求路径

在LoginCheckFilter中设置不需要处理的请求路径

    "/doc.html",
    "/webjars/**",
    "/swagger-resources",
    "/v2/api-docs"

四、Swagger 常用注解

总结

使用Swagger你只需要按照它的规范去定义接口及接口相关的信息，再通过Swagger行生出来的一系列项目和工具,就可以做到生成各种格式的接口文档，以及在线接口调试页面等等。
官网: https://swagger.io/