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

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

文章目录

[1.0 Swagger 介绍](#1.0 Swagger 介绍)

[1.1 Swagger 和 Yapi 的使用场景](#1.1 Swagger 和 Yapi 的使用场景)

[2.0 Swagger 的使用方式](#2.0 Swagger 的使用方式)

[2.1 导入 knife4j 的 maven 坐标](#2.1 导入 knife4j 的 maven 坐标)

[2.2 在配置类中加入 knife4j 相关配置](#2.2 在配置类中加入 knife4j 相关配置)

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

[2.4 完整 Swagger 的配置代码](#2.4 完整 Swagger 的配置代码)

[3.0 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 坐标

XML 复制代码

            <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 对象返回。

代码如下：

java 复制代码

    @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" 来访问该页面。

java 复制代码

    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 的配置代码

java 复制代码

/**
 * 配置类，注册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 文件中添加以下依赖项：

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 。

代码如下：

java 复制代码

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

}

效果如下：

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

代码如下：

java 复制代码

@Data
@ApiModel(description = "员工登录时传递的数据模型")
public class EmployeeLoginDTO implements Serializable {

    @ApiModelProperty("用户名")
    private String username;

    @ApiModelProperty("密码")
    private String password;

}

效果如下：

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

代码如下：

java 复制代码

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

        return Result.success();
    }

效果如下：