阅读量:1
🔥博客主页： 【小扳_-CSDN博客】
❤感谢大家点赞👍收藏⭐评论✍
文章目录
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(); }
效果如下：
