SpringBootWeb 入门了解 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 对象返回。
代码如下：
@Bean
public 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
*/
@Bean
public 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();
}效果如下：
到此这篇关于SpringBootWeb 入门了解 Swagger 的具体使用的文章就介绍到这了,更多相关SpringBootWeb Swagger使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
本文介绍了针对IntelliJ IDEA的优化配置建议,包括提升内存设置、启用G1垃圾回收器、优化垃圾回收策略以及调整网络设置等,旨在提高IDE的性能和响应速度,同时,指导用户如何修改vmoptions文件以应用这些配置,并提供了监控内存使用和插件管理的建议2024-09-09
这篇文章主要介绍了java实现数据库主键生成示例,需要的朋友可以参考下2014-03-03
这篇文章主要介绍了Java如何使用interrupt()终止线程,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2020-03-03
这篇文章主要介绍了使用log4j2关闭debug日志方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2021-12-12
这篇文章主要为大家详细介绍了java打印出国际象棋棋盘的相关代码，文中示例代码介绍的非常详细，具有一定的参考价值，感兴趣的小伙伴们可以参考一下2019-05-05
在springcloud微服务生态体系下，作为服务之间相互调用的重要组件openfeign，在其中承担着非常重要的作用，本篇以springcloud中提供的远程接口调用组件openfeign为例，来聊聊openfeign的详细使用，感兴趣的同学可以参考阅读2023-05-05
这篇文章主要介绍了Java中为什么不同的返回类型不算方法重载，方法重载是指在同一个类中，定义了多个同名方法，但每个方法的参数类型或者是参数个数不同就是方法重载，下文详细介绍，需要的小伙伴可以参考一下2022-05-05
SpringBoot集成Swagger2构建在线API文档的代码详解
这篇文章主要介绍了SpringBoot集成Swagger2构建在线API文档,本文通过实例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值，需要的朋友可以参考下2020-12-12
这篇文章主要介绍了Vue.Js及Java实现文件分片上传代码实例,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下2020-06-06
SpringMVC处理器映射器HandlerMapping详解
这篇文章主要介绍了SpringMVC处理器映射器HandlerMapping详解,在SpringMVC中会有很多请求,每个请求都需要一个HandlerAdapter处理,具体接收到一个请求之后使用哪个HandlerAdapter进行处理呢,他们的过程是什么,需要的朋友可以参考下2023-09-09
最新评论