【OpenAPI】Spring3 集成 OpenAPI 生成接口文档

Spring3 集成 OpenAPI 生成接口文档

1. 依赖

Spring 版本：3.0.5

Java 版本：jdk21

OpenAPI 依赖：

<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.6.0</version>
</dependency>

官网：OpenAPI 规范 | OpenAPI 官方文档中文版 (xiniushu.com)

不要包含其他的接口文档的框架，大概率是冲突的

目前我还没有找到 Spring3 的其他接口文档方案，swagger2 和 swagger3 都因为不兼容搞不了；

2. 配置文件

默认整个类路径全扫描

@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI springOpenAPI() {return new OpenAPI().info(new Info().title("SpringDoc API Test").description("SpringDoc Simple Application Test").version("1.0"));}}

3. 关键用法

3.1 Tag 注解

对接口文档进行分组，一个 controller 类为单位

@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1")
@Tag(name = "xxx")
public class xxxController {}

3.2 Operation 注解

对接口进行描述，一个目标方法为单位

@PostMapping("/create")
@Operation(summary = "创建一个 XXX")
public SystemJsonResponse<CustomClass> createXXX() {}

3.3 Parameter 与 Header 注解

Parameter 描述一个接口的参数与路径参数，Header 描述一个接口的请求头，他们作用于目标方法的形参

@PostMapping("/get/{id}")
@Operation(summary = "获得一个 XXX")
public SystemJsonResponse<CustomClass> getXXX(@RequestHeader("token") @Header(description = "token") String token,@PathVariable("id") @Parameter(description = "id") Long id,@RequestParam(name = "state") @Parameter(description = "state") Integer state) {
}

3.4 Schema 注解

Schema 描述一个数据模型，也可以描述一个属性，作用于类或者字段

name 可指定属性的名称，description 是属性的描述

name 作为数据模型（类）的名称，description 是数据模型（类）的描述

属性得 public 或者有 public 的 Getter 和 Setter，否则会被标注只读或只写，如果都没有则直接忽略，如果一个数据模型属性都没有，忽略这个数据模型，复杂点的情况还会出现莫名其妙的现象

总而言之规范地写就没问题，框架也没义务和精力去控制各种奇奇怪怪地情况，我们也没必要总结

@TableName(value ="user")
@Schema(description = "用户")
@Data
public class User implements Serializable {@Schema(description = "ID")private Long id;@Schema(description = "昵称")private String nickname;private static final long serialVersionUID = 1L;
}

3.5 SchemaProperty 注解

SchemaProperty 作用于一个字段，无法设置属性名，name 作为属性的描述

这个注解不能作用于自定义的数据模型，自定义对象会被认定为 string，因为这个注解就是作用于普通的字段，并不支持递归扫描，这个时候应该用 Schema

建议都用 Schema，SchemaProperty 功能还是太弱了

@SchemaProperty(name = "ID")
private Long id;

3.6 Hidden

作用于字段，表示忽略字段

@Hidden
private String nickname;

3.7 nullable = true

注解参数设置这个代表参数可以为 null

@Schema(description = "昵称", nullable = true)
private String nickname;

3.8 响应的数据模型

OpenAPI 提供了 @ApiRespnse 注解，但是很不方便，不如直接去 Postman 或者 Apifox 上进行操作，理想状态就是直接扫描出「请求body对象」和「响应body对象」 Schema 注解描述的数据模型

请求的话，作为参数是类型是确定的，OpenAPI 框架自然是扫描的到的，但是响应的数据模型，一般是统一响应格式的：

@Schema(name = "统一响应")
@NoArgsConstructor
@Getter
public class SystemJsonResponse implements Serializable {private static final long serialVersionUID = 1L;@JsonInclude@Schema(description = "状态码")private int code;@JsonInclude@Schema(description = "描述语")private String message;@JsonInclude@Schema(nullable = true)private Object data;
}

返回的时候，构造 json 是没问题的，但是框架扫描不出来这个 data 数据模型，因为框架只知道 data 是 Object 类型

你可能想问：“框架拿到 data 用 getClass 不就知道了吗？”

是的，但是接口文档生成是在这个接口被调用之前，所以并没有一个 data 数据提供给框架

你很容易想到用范型来定义统一响应：

@Schema(name = "统一响应")
@NoArgsConstructor
@Getter
public class SystemJsonResponse<T> implements Serializable {private static final long serialVersionUID = 1L;@JsonInclude@Schema(description = "状态码")private int code;@JsonInclude@Schema(description = "描述语")private String message;@JsonInclude@Schema(nullable = true)private T data;
}