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使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
这篇文章主要介绍了JavaMail入门教程之创建邮件的相关资料,具有一定的参考价值，感兴趣的小伙伴们可以参考一下2016-11-11
这篇文章主要介绍了SpringSecurity怎样使用注解控制权限的操作，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教2021-06-06
这篇文章主要为大家详细介绍了java压缩文件和下载图片示例,具有一定的参考价值，感兴趣的小伙伴们可以参考一下2016-10-10
在用Spring Security项目开发中，有时候需要放通某一个接口时，我们需要在配置中把接口地址配置上，这样做有时候显得麻烦。本文将通过一个注解的方式快速实现接口放通，感兴趣的可以了解一下2022-05-05
这篇文章主要介绍了在maven中引入本地jar包的步骤，帮助大家更好的理解和学习使用Java，感兴趣的朋友可以了解下2021-04-04
常用校验注解之@NotNull,@NotBlank,@NotEmpty的区别及说明
这篇文章主要介绍了常用校验注解之@NotNull,@NotBlank,@NotEmpty的区别及说明,具有很好的参考价值,希望对大家有所帮助,如有错误或未考虑完全的地方,望不吝赐教2024-01-01
SpringBoot集成Spring Security用JWT令牌实现登录和鉴权的方法
这篇文章主要介绍了SpringBoot集成Spring Security用JWT令牌实现登录和鉴权的方法，文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值，需要的朋友们下面随着小编来一起学习学习吧2020-05-05
Java中==运算符与equals方法的区别及intern方法详解
这篇文章主要介绍了Java中==运算符与equals方法的区别及intern方法详解的相关资料,需要的朋友可以参考下2017-04-04
在通常代码逻辑处理中,我们常常都会使用到运算符,今天我们就详细了解一下运算符的使用以及分类.运算符是对常量或者变量进行操作的符号,它分为算术运算符,赋值运算符,比较运算符,逻辑运算符以及位运算符.需要的朋友可以参考下2021-05-05
springboot整合shiro实现登录验证授权的过程解析
这篇文章主要介绍了springboot整合shiro实现登录验证授权，本文通过实例代码给大家介绍的非常详细，对大家的学习或工作具有一定的参考借鉴价值,需要的朋友可以参考下2022-01-01
最新评论