SpringBoot-使用Swagger接口文档生成

1. Swagger简介

Swagger是一个开源的API接口文档生成工具，它能够根据代码自动生成API文档，并提供一个Web页面来查看和测试API。Swagger的主要功能包括：

  • 定义RESTful API接口文档：Swagger可以根据代码注释自动生成API接口文档，包括接口描述、请求参数、响应参数、请求示例、响应示例等。
  • 接口测试：Swagger提供一个Web页面，用户可以输入API接口参数，并查看接口返回结果。
  • 接口Mock：Swagger可以模拟API接口，用户可以根据接口定义生成假数据，用于接口测试。

2. SpringBoot集成Swagger

2.1 添加依赖

在pom.xml文件中添加以下依赖：

    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.1.0</version>
    </dependency>

2.2 配置Swagger

使用SpringBoot提供的默认配置即可。

2.3 启动项目

启动项目，访问http://localhost:8080/swagger-ui.html，可以看到Swagger的默认页面。

3.Swagger接口详细说明

虽然Swagger的UI界面已经可以很好地展示后端提供的接口信息了，但是非常的混乱，我们来看看如何配置接口的一些描述信息。首先我们的页面肯定要展示一下这个文档的一些信息，只需要一个Bean就能搞定：

package com.demo.springboot_base.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfiguration {
    @Bean
    public OpenAPI springDocOpenAPI() {
        return new OpenAPI().info(new Info()
                        .title("图书管理系统 - 在线API接口文档")   //设置API文档网站标题
                        .description("这是一个图书管理系统的后端API文档，欢迎前端人员查阅！") //网站介绍
                        .version("1.0")   //当前API版本
                        .license(new License().name("我的个人博客")  //遵循的协议，这里拿来写其他的也行
                                .url("https://blog.xy21lin.cn/")));
    }
}

Swagger接口文档.jpg

接着我们来看看如何为一个Controller编写API描述信息：

//使用@Tag注解来添加Controller描述信息
@Tag(name = "账户验证相关", description = "包括用户登录、注册、验证码请求等操作。")
public class TestController {
	...
}

我们可以直接在类名称上面添加@Tag注解，并填写相关信息，来为当前的Controller设置描述信息。接着我们可以为所有的请求映射配置描述信息,使用@Operation注解描述接口信息，使用@ApiResponse注解描述返回结果的描述信息：

@ApiResponses({
       @ApiResponse(responseCode = "200", description = "测试成功"),
       @ApiResponse(responseCode = "500", description = "测试失败")   //不同返回状态码描述
})
@Operation(summary = "请求用户数据测试接口")   //接口功能描述
@ResponseBody
@GetMapping("/hello")
//请求参数描述和样例
public String hello(@Parameter(description = "测试文本数据", example = "syy") @RequestParam String text) {
    return "十一月你好";
}

对于那些不需要展示在文档中的接口，我们也可以将其忽略掉：

@Hidden
@ResponseBody
@GetMapping("/hello")
public String hello() {
    return "十一月你好";
}

对于实体类，我们也可以编写对应的API接口文档：

@Data
@Schema(description = "用户信息实体类")
public class User {
    @Schema(description = "用户编号")
    int id;
    @Schema(description = "用户名称")
    String name;
    @Schema(description = "用户邮箱")
    String email;
    @Schema(description = "用户密码")
    String password;
}

这样，我们就可以在文档中查看实体类简介以及各个属性的介绍了。不过，这种文档只适合在开发环境下生成，如果是生产环境，我们需要关闭文档：

springdoc:
  api-docs:
    enabled: false