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

🔥博客主页： 【小扳_-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();}

效果如下：