Spring Boot：Swagger生成接口文档并调试接口

💥 该系列属于【SpringBoot基础】专栏，如您需查看其他SpringBoot相关文章，请您点击左边的连接

目录

一、Swagger介绍

二、Swagger常用的注解

三、代码示例

1. 项目结构

2. 依赖引入

3. WebMvc配置类（配置Swagger文档）

4. pojo（@ApiModel和@ApiModelProperty）

5. controller（@Api和@ApiOperation）

四、接口测试

1. 字符串测试接口

2. 数组测试接口

3. 列表（集合）测试接口

4. 实体类测试接口

5. 实体类测试接口（以JSON格式传参）

---

一、Swagger介绍

使用Swagger只需要按照它的规范去定义接口及接口相关的信息，就可以做到生成接口文档，以及在线接口调试页面。官网：https://swagger.io/

核心特性

• 文档生成：Swagger 可以自动生成 API 文档，这些文档是实时更新的，与代码保持同步。

• API 测试：Swagger UI 允许开发者在浏览器中直接测试 API，无需编写任何代码。

Knife4j是为JavaMVC框架集成Swagger生成Api文档的增强解决方案。

二、Swagger常用的注解

三、代码示例

1. 项目结构

2. 依赖引入

        <!-- Swagger生成接口文档和接口测试,Knife4j为增强版 -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-spring-boot-starter</artifactId>
            <version>3.0.2</version>
        </dependency>

3. WebMvc配置类（配置Swagger文档）

/**
 * 配置类，注册web层相关组件
 */
@Configuration
public class WebMvcConfiguration extends WebMvcConfigurationSupport {

    /**
     * 注册自定义拦截器
     *
     * @param registry
     */
    protected void addInterceptors(InterceptorRegistry registry) {
        /**
         registry.addInterceptor(jwtTokenAdminInterceptor)
         .addPathPatterns("/admin/**")
         .excludePathPatterns("/admin/employee/login");

         registry.addInterceptor(jwtTokenUserInterceptor)
         .addPathPatterns("/user/**")
         .excludePathPatterns("/user/user/login")
         .excludePathPatterns("/user/shop/status");
         */
    }

    @Bean
    public Docket docket1() {

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("这是项目接口文档标题")
                .version("2.1")
                .description("这是项目接口文档简介")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("管理端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.admin"))      //指定生成接口需要扫描的包
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket docket2() {

        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("这是项目接口文档标题")
                .version("2.1")
                .description("这是项目接口文档简介")
                .build();

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("用户端接口")
                .apiInfo(apiInfo)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.user"))     //指定生成接口需要扫描的包
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 设置静态资源映射，主要是访问接口文档（html、js、css）
     *
     * @param registry
     */
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // "/doc.html"视作静态资源，而不是controller请求

        registry.addResourceHandler("/doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }


}

4. pojo（@ApiModel和@ApiModelProperty）

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "这是Person类")
public class Person {
    @ApiModelProperty("身份证号")
    int id;
    @ApiModelProperty("姓名")
    String name;
    @ApiModelProperty("年龄")
    int age;
}

5. controller（@Api和@ApiOperation）

@Api(tags = "管理员相关接口")
@RestController
public class AdminController {
    @ApiOperation(value = "字符串测试接口")
    @GetMapping("/AdminStringTest")
    public String AdminStringTest(String string) {
        return "receive: " + string;
    }

    @ApiOperation(value = "数组测试接口")
    @GetMapping("/AdminIntegerArrTest")
    public String AdminIntegerArrTest(Integer[] integers) {
        return "receive: " + Arrays.toString(integers);
    }

    @ApiOperation(value = "列表测试接口")
    @GetMapping("/AdminListTest")
    public String AdminListTest(@RequestParam(value = "list") List<Integer> list) {
        return "receive: " + list.toString();
    }

    @ApiOperation(value = "实体类测试接口")
    @GetMapping("/AdminEntityTest")
    public String AdminEntityTest(Person person) {
        return "receive: " + person.toString();
    }

    @ApiOperation(value = "实体类测试接口(以JSON格式传参)")
    @GetMapping("/AdminEntityJsonTest")
    public String AdminEntityJsonTest(@RequestBody Person person) {
        return "receive: " + person.toString();
    }

}

四、接口测试

首先在浏览器中输入http://localhost:8080/doc.html

然后选择管理端接口，进入管理员相关接口，就可以看见controller中所有方法的测试。

1. 字符串测试接口

2. 数组测试接口

3. 列表（集合）测试接口

4. 实体类测试接口

5. 实体类测试接口（以JSON格式传参）

测试发现结果出错：

2024-08-01 16:09:11.419  WARN 76660 --- [nio-8080-exec-2] .w.s.m.s.DefaultHandlerExceptionResolver : Resolved [org.springframework.http.converter.HttpMessageNotReadableException: Required request body is missing: public java.lang.String com.example.controller.admin.AdminController.AdminEntityJsonTest(com.example.pojo.Person)]

原因：
GetMapping要改成PostMapping，修改后的代码为：

    @ApiOperation(value = "实体类测试接口(以JSON格式传参)")
    @PostMapping("/AdminEntityJsonTest")
    public String AdminEntityJsonTest(@RequestBody Person person) {
        return "receive: " + person.toString();
    }

测试结果：