当前位置：首页 > news >正文

SpringBootWeb 篇-入门了解 Swagger 的具体使用

news 2025/8/4 7:57:00

🔥博客主页：【小扳_-CSDN博客】
❤感谢大家点赞👍收藏⭐评论✍

文章目录

1.0 Swagger 介绍

1.1 Swagger 和 Yapi 的使用场景

2.0 Swagger 的使用方式

2.1 导入 knife4j 的 maven 坐标

2.2 在配置类中加入 knife4j 相关配置

2.3 设置静态资源映射，否则接口文档页面无法访问

2.4 完整 Swagger 的配置代码

3.0 Swagger 常见的注解

1.0 Swagger 介绍

使用 Swagger 你只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。

knife4j 是为 Java MVC 框架集成 Swagger 生成 Api 文档的增强解决方案。Swagger 允许定义 API 的各种方面，包括输入参数、请求和响应的数据格式、接口路径等内容。同时， Swagger 提供了一个交互式的 Swagger UI ，可以直观地查看和测试 API 。

简单来说，就是 Swagger 框架可以根据已经实现的方法或者类，通过页面的方式直观清晰的查看或者进行测试该方法。

1.1 Swagger 和 Yapi 的使用场景

1）Yapi 是设计阶段使用的工具，管理和维护接口。

2）Swagger 在开发阶段使用的框架，帮助后端开发人员的接口测试。

2.0 Swagger 的使用方式

首先通过导入 knife4j 的 maven 坐标，再在配置类中加入 knife4j 相关配置，最后设置静态资源映射。

2.1 导入 knife4j 的 maven 坐标

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

2.2 在配置类中加入 knife4j 相关配置

首先创建一个配置类，在普通类上加上 @Configuration 注解，且该类需要继承 WebMvcConfigurationSupport 类。

再定义一个返回 Docket 的 docket 方法，且该方法需要加上 @Bean 注解，使其交给 IOC 容器管理，成为 Bean 对象。

在该 docket 方法中先创建一个 ApiInfo 对象，通过 apiInfo 的一些方法来设置属性，再创建一个 Docket 对象，通过 docket 的一些方法来设置属性，再将设置好的 docket 对象返回。

代码如下：

    @Beanpublic Docket docket() {ApiInfo apiInfo = new ApiInfoBuilder().title("项目接口文档").version("2.0").description("项目接口文档").build();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("需要扫描的项目名")).paths(PathSelectors.any()).build();return docket;}

其中设置 apis(RequestHandlerSelectors.basePackage("需要扫描的项目名")) 该属性是很重要的，项目中要测试的方法或者类在具体包的包名。这样就会自动扫描该包及其子包的方法或者类。

2.3 设置静态资源映射，否则接口文档页面无法访问

重写配置类中的 addResourceHandlers 方法，通过该资源路径 "/doc.html" 来访问该页面。

    protected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}

2.4 完整 Swagger 的配置代码


/*** 配置类，注册web层相关组件*/
@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {/*** 通过knife4j生成接口文档* @return*/@Beanpublic Docket docket() {ApiInfo apiInfo = new ApiInfoBuilder().title("项目接口文档").version("2.0").description("项目接口文档").build();Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo).select().apis(RequestHandlerSelectors.basePackage("需要测试方法所在项目的包名")).paths(PathSelectors.any()).build();return docket;}/*** 设置静态资源映射* @param registry*/protected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

具体的页面效果：

通过访问 "/doc.html" 的资源路径，就可以访问到该页面，通过该页面就可以非常方便测试这些方法了。

补充：

若要使用 .built 来创建对象，你需要导入 Lombok 这个库的 Maven 坐标。在 Maven 项目中，你可以在 pom.xml 文件中添加以下依赖项：

<dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><version>1.18.20</version>
</dependency>

实际上，使用 .builder 创建对象是针对 Lombok 中的 @Builder 注解的功能。要使用 Lombok 的 @Builder 注解创建对象，你需要在你的Java类中添加 @Builder 注解，而不是导入特定的 Lombok 库的 Maven 坐标。

3.0 Swagger 常见的注解

通过注解可以控制生成的接口文档，使用接口文档拥有更好的可读性。简单来说，通过这些注解就可以对类、方法、方法中的属性进行说明，在测试方法的过程中，可以很清晰的明白该方法或者类的用途、信息。

常用注解如下：

1）@Api("tags=对类的描述")：用在类上，比如 Controller ，表示对类的说明。

代码如下：

效果如下：

2）@ApiModel(description="对实体类进行描述")：用在实体类上，比如 entity、DTO、VO 。

代码如下：

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;}

效果如下：

3）@ApiModelProperty("对属性进行描述")：用在属性上，描述属性信息。

代码如下：

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;}

效果如下：

4）@ApiOperation("对方法进行描述")：用在方法上，例如 Controller 的方法，说明方法的用途、作用。

代码如下：

    @PostMapping@ApiOperation("新增员工")public Result<String> save(@RequestBody EmployeeDTO employeeDTO){log.info("新增员工");employeeService.save(employeeDTO);return Result.success();}

效果如下：