Spring Boot 接口测试：Postman + Swagger 实战（完整版）

码客日记

墨衍会员 · AI 创作全网分发码龄6年

关注

原创最新推荐文章于 2026-09-28 10:51:52 发布 1.7k 阅读 AI 写同款· GEO 优化 ›

最强PostMan使用教程（6）- 使用Postman导入swagger OPEN API 好久没有更新这个系列的文章了，最近使用postman去测试数字货币交易所的API接口，让我们继续吧, 阅读详情

Spring Boot 接口测试：Postman + Swagger 实战（完整版）

在Spring Boot接口开发中，“接口文档编写”和“接口测试验证”是两个高频且关键的环节——没有规范的接口文档，前后端对接易出现分歧；没有高效的测试工具，接口功能验证、问题排查会十分繁琐。

本文基于前文实现的「Spring Boot + MyBatis-Plus 单表CRUD + 统一返回格式 + 全局异常处理」项目，手把手实战 Postman 接口调试 + Swagger 接口文档自动生成，覆盖“文档生成→接口测试→问题排查”全流程，解决新手“不会写接口文档”“接口测试效率低”的痛点，贴合企业实际开发场景。

前置说明：本文基于Spring Boot 2.7.x版本，无缝衔接之前的用户管理CRUD接口（/api/user相关），所有操作可直接在现有项目中落地，无需额外新建项目；Swagger选用稳定的Knife4j（基于Swagger 2.0封装，UI更友好、配置更简单），避免Swagger 3.0与Spring Boot 2.7.x的兼容性问题。

一、核心目标与工具选型

1. 核心目标

Swagger：自动生成接口文档，替代手动编写文档，支持接口在线调试、参数说明、返回格式展示，降低前后端对接成本；
Postman：高效调试接口，支持接口保存、批量测试、环境配置、参数传递，验证接口功能是否符合预期（如CRUD、异常处理、统一返回格式）。

2. 工具选型说明

Swagger 选型：Knife4j（Spring Boot Starter 方式集成，无需复杂配置，UI美观，支持接口排序、文档导出，适配Spring Boot 2.7.x）；
Postman 选型：最新版Postman（免费够用，支持Windows/Mac/Linux，功能完善，适合个人开发和团队协作）；
适配前提：项目已实现「统一返回格式」和「全局异常处理」，接口返回结构一致（Result），避免Swagger文档展示混乱。

二、第一步：集成 Swagger（Knife4j），自动生成接口文档

传统Swagger配置繁琐，且UI不够友好，本文选用Knife4j（国人开发的Swagger增强工具），通过导入依赖、简单配置，即可自动扫描接口，生成规范的接口文档，支持在线调试。

1. 导入Knife4j依赖（pom.xml）

在现有项目的pom.xml中，添加Knife4j的Spring Boot Starter依赖，无需额外导入Swagger核心依赖（Knife4j已内置），注意版本与Spring Boot 2.7.x适配。

<!-- Knife4j Swagger 增强工具（适配Spring Boot 2.7.x） -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

<!-- 若项目中未引入spring-boot-starter-web，需额外添加（本文项目已存在） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

2. 编写Swagger核心配置类

创建Swagger配置类，配置文档基本信息（项目名称、作者、版本）、接口扫描范围、全局参数等，确保Swagger能正确扫描到Controller接口，生成完整文档。

package com.example.cruddemo.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger（Knife4j）配置类
 * 核心：配置接口扫描范围、文档信息，开启Knife4j增强功能
 */
@Configuration  // 标记为配置类，交给Spring管理
@EnableSwagger2  // 开启Swagger 2.0功能（Knife4j基于Swagger 2.0）
@EnableKnife4j   // 开启Knife4j增强功能（UI美化、文档导出等）
public class SwaggerConfig implements WebMvcConfigurer {

    /**
     * 配置Docket实例，指定Swagger文档的基本信息和扫描范围
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置文档基本信息（页面顶部展示）
                .apiInfo(apiInfo())
                // 是否开启Swagger（生产环境建议关闭，避免暴露接口）
                .enable(true)
                // 配置接口扫描策略
                .select()
                // 扫描指定包下的接口（修改为你的Controller包路径，关键！）
                .apis(RequestHandlerSelectors.basePackage("com.example.cruddemo.controller"))
                // 扫描所有接口（除了被@ApiIgnore注解标记的接口）
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 配置Swagger文档基本信息（标题、作者、版本、描述等）
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题（必填）
                .title("Spring Boot 接口文档（用户管理CRUD）")
                // 文档描述（可选，说明接口用途）
                .description("基于Spring Boot + MyBatis-Plus + Knife4j + Postman 实战，包含用户CRUD、统一返回、全局异常处理接口")
                // 作者信息（姓名、网址、邮箱，可选）
                .contact(new Contact("开发者", "https://xxx.com", "xxx@163.com"))
                // 接口版本（可选，与项目版本一致）
                .version("1.0.0")
                // 文档版权信息（可选）
                .license("Apache 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }
}

3. 配置Swagger访问权限（避免拦截，关键）

若项目中未配置拦截器，可跳过此步骤；若配置了拦截器（如登录拦截），需放行Swagger相关的路径，否则无法访问接口文档页面。

// 若有拦截器配置类，添加以下放行逻辑（示例）
@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new LoginInterceptor())
            .addPathPatterns("/**")  // 拦截所有接口
            // 放行Swagger相关路径，避免拦截
            .excludePathPatterns(
                    "/swagger-ui.html",
                    "/swagger-ui/**",
                    "/swagger-resources/**",
                    "/v2/api-docs",
                    "/v3/api-docs",
                    "/doc.html",  // Knife4j的默认访问路径
                    "/webjars/**"
            );
}

4. 接口添加Swagger注解（优化文档展示）

通过Swagger注解，给Controller、接口方法、参数添加说明，让生成的文档更清晰（无需添加注解也能生成文档，但可读性差），常用注解如下：

@Api：用在Controller类上，描述Controller的用途；
@ApiOperation：用在接口方法上，描述接口的功能、请求方式；
@ApiParam：用在接口参数上，描述参数的含义、是否必填；
@ApiModel：用在实体类上，描述实体类的用途（如User实体）；
@ApiModelProperty：用在实体类字段上，描述字段的含义、类型、是否必填；
@ApiIgnore：用在接口/参数上，标记为忽略，不生成到接口文档中。

修改UserController和User实体类，添加Swagger注解：

4.1 实体类（User.java）添加注解

package com.example.cruddemo.entity;

import com.baomidou.mybatisplus.annotation.*;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.hibernate.validator.constraints.Length;

import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Positive;
import java.util.Date;

/**
 * 用户实体类，对应数据库user表
 */
@Data
@TableName("user")
@ApiModel(value = "User对象", description = "用户信息实体类，对应数据库user表") // Swagger注解：描述实体类
public class User {

    @TableId(type = IdType.AUTO)
    @ApiModelProperty(value = "用户主键ID", example = "1", dataType = "Long", hidden = false) // 描述字段
    private Long id;

    @NotBlank(message = "用户名不能为空")
    @Length(min = 1, max = 30, message = "用户名长度必须在1-30之间")
    @ApiModelProperty(value = "用户名", required = true, example = "张三", dataType = "String", notes = "长度1-30，不能为空")
    private String name;

    @NotNull(message = "年龄不能为空")
    @Positive(message = "年龄必须为正数")
    @ApiModelProperty(value = "用户年龄", required = true, example = "22", dataType = "Integer", notes = "必须为正数")
    private Integer age;

    @Email(message = "邮箱格式不正确")
    @ApiModelProperty(value = "用户邮箱", example = "zhangsan@163.com", dataType = "String", notes = "需符合邮箱格式")
    private String email;

    @TableField(value = "create_time", fill = FieldFill.INSERT)
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") // 格式化时间，便于文档展示
    @ApiModelProperty(value = "创建时间", dataType = "Date", hidden = true) // hidden=true：不展示在文档参数中（自动填充）
    private Date createTime;

    @TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    @ApiModelProperty(value = "更新时间", dataType = "Date", hidden = true)
    private Date updateTime;
}

4.2 Controller（UserController.java）添加注解

package com.example.cruddemo.controller;

import com.example.cruddemo.common.BusinessException;
import com.example.cruddemo.common.Result;
import com.example.cruddemo.common.ResultCode;
import com.example.cruddemo.entity.User;
import com.example.cruddemo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import java.util.List;

/**
 * 用户控制层，编写CRUD接口
 */
@RestController
@RequestMapping("/api/user")
@Api(tags = "用户管理接口", description = "包含用户新增、查询、修改、删除等CRUD接口，统一返回Result格式") // Swagger注解：描述Controller
@Validated
public class UserController {

    @Autowired
    private UserService userService;

    // 1. 新增用户（POST请求）
    @PostMapping("/add")
    @ApiOperation(value = "新增用户", notes = "新增用户，用户名不能为空、年龄必须为正数，创建时间自动填充", httpMethod = "POST")
    public Result<Void> addUser(
            @ApiParam(value = "用户信息实体", required = true, notes = "需传入name、age，email可选")
            @Valid @RequestBody User user) {
        boolean exists = userService.lambdaQuery().eq(User::getName, user.getName()).exists();
        if (exists) {
            throw new BusinessException(ResultCode.USER_NAME_DUPLICATE);
        }
        userService.save(user);
        return Result.success();
    }

    // 2. 根据ID查询用户（GET请求）
    @GetMapping("/{id}")
    @ApiOperation(value = "根据ID查询用户", notes = "传入用户ID，查询单个用户详情，ID不存在则返回用户不存在异常", httpMethod = "GET")
    public Result<User> getUserById(
            @ApiParam(value = "用户ID", required = true, example = "1", notes = "用户主键ID，Long类型")
            @NotNull(message = "用户ID不能为空") @PathVariable Long id) {
        User user = userService.getById(id);
        if (user == null) {
            throw new BusinessException(ResultCode.USER_NOT_EXIST);
        }
        return Result.success(user);
    }

    // 3. 查询所有用户（GET请求）
    @GetMapping("/list")
    @ApiOperation(value = "查询所有用户", notes = "无需传入参数，查询所有用户列表，返回用户集合", httpMethod = "GET")
    public Result<List<User>> getUserList() {
        return Result.success(userService.list());
    }

    // 4. 根据ID修改用户（PUT请求）
    @PutMapping("/update")
    @ApiOperation(value = "根据ID修改用户", notes = "传入用户信息（必须包含ID），修改非null字段，ID不存在则修改失败", httpMethod = "PUT")
    public Result<Void> updateUser(
            @ApiParam(value = "用户信息实体（含ID）", required = true, notes = "必须传入id，其他字段非必填（非null则修改）")
            @Valid @RequestBody User user) {
        userService.updateById(user);
        return Result.success();
    }

    // 5. 根据ID删除用户（DELETE请求）
    @DeleteMapping("/{id}")
    @ApiOperation(value = "根据ID删除用户", notes = "传入用户ID，删除对应用户，ID不存在则删除失败", httpMethod = "DELETE")
    public Result<Void> deleteUser(
            @ApiParam(value = "用户ID", required = true, example = "1", notes = "用户主键ID，Long类型")
            @NotNull(message = "用户ID不能为空") @PathVariable Long id) {
        userService.removeById(id);
        return Result.success();
    }

    // 6. 根据姓名查询用户
    @GetMapping("/list/name")
    @ApiOperation(value = "根据姓名查询用户", notes = "传入用户名，查询该姓名对应的所有用户（支持模糊匹配，本文为精确匹配）", httpMethod = "GET")
    public Result<List<User>> getUserByName(
            @ApiParam(value = "用户名", required = true, example = "张三", notes = "用户名不能为空")
            @NotBlank(message = "用户名不能为空") @RequestParam String name) {
        List<User> userList = userService.lambdaQuery().eq(User::getName, name).list();
        return Result.success(userList);
    }
}

5. 启动项目，访问Swagger文档

启动Spring Boot项目，确保无报错（依赖下载完成、配置正确）；
访问Knife4j文档页面（默认路径）：http://localhost:8081/crud-demo/doc.html（注意替换为你的项目端口和上下文路径）；
- 端口：application.yml中配置的server.port（本文为8081）；
- 上下文路径：server.servlet.context-path（本文为/crud-demo，若无则直接访问http://localhost:8081/doc.html）。
访问成功后，即可看到接口文档页面，包含「文档信息、接口列表、参数说明、在线调试」等功能（如下图示意，无需截图，按步骤可直接访问）。

6. Swagger在线调试接口（实战）

Swagger支持在线调试接口，无需打开Postman，即可快速验证接口功能，以「新增用户」为例，步骤如下：

在文档页面，点击左侧「用户管理接口」→ 找到「新增用户」接口 → 点击「调试」按钮；
在请求参数区域，填写JSON格式的用户信息（根据@ApiModelProperty提示填写），示例：
{ "name": "张三", "age": 22, "email": "zhangsan@163.com" }
点击「发送」按钮，查看响应结果（统一返回格式），若返回{"code":200,"msg":"操作成功","data":null}，说明接口调试成功；
其他接口（查询、修改、删除）调试步骤类似，根据接口提示传入参数，发送请求，验证响应结果是否符合预期。

7. Swagger文档导出（可选，团队协作常用）

Knife4j支持导出接口文档（HTML、Markdown、Word等格式），便于团队共享，步骤：

文档页面顶部 → 点击「文档下载」→ 选择需要导出的格式（如Markdown）→ 保存到本地，即可生成规范的接口文档。

Swagger集成踩坑点

踩坑1：访问doc.html报404 → 原因：未放行Swagger相关路径（拦截器拦截），或依赖版本不兼容；解决方案：配置拦截器放行Swagger路径，确保Knife4j版本为3.0.3（适配Spring Boot 2.7.x）。
踩坑2：接口文档无接口展示 → 原因：Swagger配置类中，basePackage配置错误（未指向Controller包）；解决方案：修改RequestHandlerSelectors.basePackage(“你的Controller包路径”)。
踩坑3：实体类字段说明不显示 → 原因：未给实体类/字段添加@ApiModel、@ApiModelProperty注解；解决方案：补充对应Swagger注解，确保注解配置正确。

三、第二步：Postman 实战，高效调试接口

Swagger适合在线快速调试、查看接口文档，而Postman适合长期开发、批量测试、复杂场景调试（如参数传递、环境切换），两者配合使用，效率翻倍。本文基于前面的用户管理接口，实战Postman的核心用法。

1. Postman准备工作

下载并安装Postman（官网：https://www.postman.com/，免费注册账号即可使用）；
启动Postman，创建工作空间（如「Spring Boot 接口测试」），用于管理当前项目的所有接口；
创建接口集合（Collection），命名为「用户管理CRUD接口」，用于归类当前项目的接口（避免接口混乱）。

2. 配置Postman环境（优化，可选）

若项目有多个环境（开发环境、测试环境、生产环境），可配置Postman环境，避免每次调试接口都修改请求地址，步骤：

点击Postman顶部「环境」→ 点击「Add Environment」；
环境名称：填写「开发环境」；
添加环境变量：
- 变量名：baseUrl，变量值：http://localhost:8081/crud-demo（项目基础路径）；
- 变量名：port，变量值：8081（可选）；
点击「Save」保存环境，使用时选择「开发环境」，接口地址可直接引用变量（如{{baseUrl}}/api/user/add）。

3. Postman调试接口（逐个实战，贴合CRUD）

以下按「新增→查询→修改→删除」的顺序，实战每个接口的调试，确保接口功能正常、统一返回格式正确、异常处理生效。

3.1 调试「新增用户」接口（POST请求）

在「用户管理CRUD接口」集合下，点击「Add Request」，命名为「新增用户」；
请求方式：选择POST；
请求地址：{{baseUrl}}/api/user/add（或直接填写http://localhost:8081/crud-demo/api/user/add）；
请求体（Body）：选择raw → 格式选择JSON，填写参数（与Swagger调试一致）：
{ "name": "张三", "age": 22, "email": "zhangsan@163.com" }
点击「Send」发送请求，查看响应结果（符合统一返回格式）：
{ "code": 200, "msg": "操作成功", "data": null }
异常场景测试：故意填写错误参数（如name为空、age为负数），发送请求，验证全局异常处理是否生效，响应示例（参数错误）：
{ "code": 400, "msg": "用户名不能为空", "data": null }

3.2 调试「根据ID查询用户」接口（GET请求）

新建请求，命名为「根据ID查询用户」；
请求方式：选择GET；
请求地址：{{baseUrl}}/api/user/1（1为新增用户的ID，替换为你实际新增的ID）；
无需填写请求体（GET请求参数在地址栏），点击「Send」，响应结果（携带用户数据）：
{ "code": 200, "msg": "操作成功", "data": { "id": 1, "name": "张三", "age": 22, "email": "zhangsan@163.com", "createTime": "2024-05-20 10:30:00", "updateTime": "2024-05-20 10:30:00" } }
异常场景测试：查询不存在的ID（如999），响应结果（业务异常）：
{ "code": 1001, "msg": "用户不存在", "data": null }

3.3 调试「查询所有用户」接口（GET请求）

新建请求，命名为「查询所有用户」；
请求方式：GET；
请求地址：{{baseUrl}}/api/user/list；
点击「Send」，响应结果（返回用户列表）：

{
 "code": 200,
 "msg": "操作成功",
 "data": [
   {
     "id": 1,
     "name": "张三",
     "age": 22,
     "email": "zhangsan@163.com",
     "createTime": "2024-05-20 10:30:00",
     "updateTime": "2024-05-20 10:30:00"
   }
 ]
}

3.4 调试「根据ID修改用户」接口（PUT请求）

新建请求，命名为「根据ID修改用户」；
请求方式：PUT；
请求地址：{{baseUrl}}/api/user/update；
请求体：raw → JSON，填写参数（必须包含ID，修改需要更新的字段）：

{
  "id": 1,
  "age": 23,
  "email": "zhangsan_update@163.com"
}

点击「Send」，响应结果：

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

验证：再次调用「根据ID查询用户」接口，查看用户年龄和邮箱是否已更新。

3.5 调试「根据ID删除用户」接口（DELETE请求）

新建请求，命名为「根据ID删除用户」；
请求方式：DELETE；
请求地址：{{baseUrl}}/api/user/1（ID为需要删除的用户ID）；
点击「Send」，响应结果：

{
  "code": 200,
  "msg": "操作成功",
  "data": null
}

验证：调用「查询所有用户」接口，查看该用户是否已被删除。

4. Postman高级用法（提升效率，实战必备）

4.1 接口参数传递（关联接口，无需手动输入）

场景：新增用户后，需要用新增的ID查询/修改/删除，无需手动记录ID，可通过Postman的「环境变量」传递参数，步骤：

调试「新增用户」接口时，在响应结果中，提取用户ID（需要项目新增后回显ID，本文已实现）；
在「新增用户」请求的「Tests」标签页，编写脚本，将ID存入环境变量：

// 解析响应JSON
var responseJson = pm.response.json();
// 将新增的用户ID存入环境变量（变量名：userId）
pm.environment.set("userId", responseJson.data.id);

发送「新增用户」请求后，环境变量userId会自动赋值；
后续接口（查询、修改、删除）的地址可直接引用该变量：{{baseUrl}}/api/user/{{userId}}。

4.2 批量测试接口（Collection Runner）

场景：接口修改后，需要批量验证所有接口是否正常，无需逐个点击发送，步骤：

整理好所有接口（确保接口顺序正确，如新增→查询→修改→删除）；
选中「用户管理CRUD接口」集合，点击右侧「Runner」按钮；
选择环境（如开发环境），设置迭代次数（如1次），点击「Run 用户管理CRUD接口」；
Postman会自动按顺序执行所有接口，执行完成后，显示每个接口的执行结果（成功/失败），便于快速排查问题。

4.3 接口导出/导入（团队协作）

场景：将本地调试好的接口，分享给团队成员，步骤：

导出：选中集合 → 点击「…」→ 选择「Export」→ 选择导出格式（推荐Collection v2.1）→ 保存文件；
导入：团队成员打开Postman → 点击「Import」→ 选择导出的文件 → 导入成功，即可直接使用接口。

Postman调试踩坑点

踩坑1：POST/PUT请求无响应或参数校验失败 → 原因：请求体格式错误（未选择JSON），或参数缺失/格式不正确；解决方案：确保请求体为raw→JSON格式，参数与接口要求一致（参考Swagger文档）。
踩坑2：GET请求参数传递错误 → 原因：将参数写在请求体中（GET请求参数应在地址栏或Params标签页）；解决方案：在Params标签页填写GET请求参数，或直接拼接在地址栏。
踩坑3：环境变量引用失败 → 原因：未选择对应的环境，或变量名拼写错误；解决方案：选择正确的环境，核对变量名（区分大小写）。