用Swagger进行后端接口测试的实战操作

目录

一.什么是Swagger？

二.Swagger的使用操作流程：

1.在pom.xml配置文件导入 Knife4j 的依赖：

2.在config配置类中加入 Knife4j 的相关配置并设置静态资源映射（否则接口文档无法访问）：

三.Swagger的四个常用注解：

1.注解介绍：

（1） @Api

（2）. @ApiOperation

（3）. @ApiModel

（4）. @ApiModelProperty

 2.注解代码演示：

四.Swagger接口文档的效果展示：

---

一.什么是Swagger？

使用Swagger的时候，按照它的规范去定义接口以及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。

官网：https://swagger.io/

Knife4j是为Java MVC框架集成Swagger生成的Api文档的增强解决方案。Knife4j 提供了一个比默认的 Swagger UI 更加美观和功能丰富的界面。它支持多种主题、分组管理、接口调试等功能，用户可以通过更友好的界面快速查看和测试 API。 我们可以通过 UI 直接在页面上对 API 进行测试，而不需要借助其他工具（如 Postman 等）。

knife4j-spring-boot-starter 是针对 Spring Boot 的集成库，它让 Knife4j 与 Spring Boot 项目的集成更加简单，只需要添加依赖即可自动生成 API 文档，不需要复杂的配置。

---

二.Swagger的使用操作流程：

1.在pom.xml配置文件导入 Knife4j 的依赖：

<!--springfox swagger官方Starter-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
    
<!--knife4j-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

2.在config配置类中加入 Knife4j 的相关配置并设置静态资源映射（否则接口文档无法访问）：

@Configuration
@Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {
    /**
     * 通过knife4j生成接口文档
     * @return
     */
    @Bean
    public Docket docket1() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("****项目接口文档")  // API 文档的标题
                .version("2.0")            // API 文档的版本号
                .description("****项目接口文档") // API 文档的描述信息
                .build();
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")  //为该 Docket 实例设置一个分组名称为"管理端接口"。这可以方便将项目中的不同 API 分成不同的文档组
                .apiInfo(apiInfo)  //设置 API 文档的基本信息（之前创建的 ApiInfo 对象）
                .select()  //启动选择器，用于进一步筛选哪些接口需要生成文档
                //指定生成接口需要扫描的包,只扫描 com.sky.controller.admin 包下的接口，并生成文档
                .apis(RequestHandlerSelectors.basePackage("com.sky.controller.admin"))
                //对于所有路径的接口都会生成文档
                .paths(PathSelectors.any())  
                .build();
        return docket;
    }
    /**
     * 设置静态资源映射
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        //我们就可以通过url为localhost:8080/doc.html的请求路径查阅接口文档，而生成完接口文档后，设置静态资源的实际存储位置来使这些文件就会放在classpath:/META-INF/resources/路径下
        registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");
    }
}

---

三.Swagger的四个常用注解：

1.注解介绍：

注解	说明
@Api	用在类上，说明该类的作用（例如Controller来表示对类的说明）
@ApiOperation	注解来给API增加方法说明（例如Controller的方法来说明方法的用途与作用）
@ApiModel	用在类上，描述一个Model的信息（例如entity,DTO,VO）（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty	用在属性上，描述一个model的属性

（1） @Api

• 位置: 用于类（Controller 类）上。
• 作用: 用来标识该类是一个 Swagger 资源，并为类提供相关的描述信息。在生成的文档中，该注解可以帮助分组和分类接口。
• 常用属性:
  • value: API 的简短描述，通常用于界面上的标签。
  • tags: 用于给接口进行分类或分组，常用于多个控制器之间的归类。
  • description: 该类提供的详细描述。

@Api(value = "用户管理", tags = {"用户相关接口"}, description = "提供用户的增删改查等功能")
@RestController
public class UserController {
    // Controller logic
}

（2）. @ApiOperation

• 位置: 用于方法上。
• 作用: 用于描述接口方法的用途，并生成文档中每个具体 API 操作的描述。帮助明确说明某个 API 方法的功能，并提供一些额外的信息，如是否支持 GET/POST 请求等。
• 常用属性:
  • value: API 方法的简短描述。
  • notes: 提供额外的说明或描述，通常用于详细说明 API 的用途或注意事项。
  • httpMethod: 指定 API 方法支持的 HTTP 请求类型，如 GET, POST, PUT 等。

@ApiOperation(value = "根据ID获取用户信息", notes = "传入用户ID，返回该用户的详细信息")
@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    // 业务逻辑
    return userService.findUserById(id);
}

（3）. @ApiModel

• 位置: 用于实体类（Model 类）上。
• 作用: 用于描述请求或响应数据模型（即 Java 实体类），帮助生成文档中的对象模型描述。通常用于描述接口请求参数或响应数据的结构。
• 常用属性:
  • value: 模型的简短描述。
  • description: 对模型类进行更详细的描述。

@ApiModel(value = "用户实体", description = "用户的基本信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;

    @ApiModelProperty(value = "用户名", example = "John Doe")
    private String name;

    @ApiModelProperty(value = "用户邮箱", example = "john@example.com")
    private String email;

    // getters and setters
}

（4）. @ApiModelProperty

• 位置: 用于实体类的属性字段上。
• 作用: 用于描述模型类中的每个字段，帮助生成文档中对每个属性的详细说明。可以指定属性的名称、示例值、是否必须、备注等。
• 常用属性:
  • value: 字段的简短描述。
  • example: 该字段的示例值。
  • required: 是否为必填项，默认为 false。
  • hidden: 是否在文档中隐藏该字段，默认为 false。
  • notes: 提供额外的描述说明。

@ApiModel(value = "用户实体", description = "用户的基本信息")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1", required = true)
    private Long id;

    @ApiModelProperty(value = "用户名", example = "John Doe")
    private String name;

    @ApiModelProperty(value = "用户邮箱", example = "john@example.com")
    private String email;

    @ApiModelProperty(value = "用户密码", hidden = true)
    private String password;

    // getters and setters
}

 2.注解代码演示：

 像下面代码一样将注解加在类或方法的上面并加入字符串进行说明。

@RestController("userSetmealController")
@RequestMapping("/user/setmeal")
@Api(tags = "C端-套餐浏览接口")
public class SetmealController {
    @Autowired
    private SetmealService setmealService;

    @GetMapping("/list")
    @ApiOperation("根据分类id查询套餐")
    @Cacheable(cacheNames = "setmealCache" , key = "#categoryId")  //key为 setmealCache::100
    public Result<List<Setmeal>> list(Long categoryId) {
        Setmeal setmeal = new Setmeal();
        setmeal.setCategoryId(categoryId);
        setmeal.setStatus(StatusConstant.ENABLE);

        List<Setmeal> list = setmealService.list(setmeal);
        return Result.success(list);
    }
}

---

四.Swagger接口文档的效果展示：

我们可以通过下面这样的整洁页面来调用接口进行测试 - > 

 

随后我们就明白可以通过Swagger来代替Postman进行后端的接口测试。

---

好了，本期内容就介绍到这里，Javaweb的知识还在生成中，记得三连支持以便找不到更多精彩内容，好了感谢收看！！！