Spring3 集成 OpenAPI 生成接口文档
1. 依赖
Spring 版本:3.0.5
Java 版本:jdk21
OpenAPI 依赖:
xml
<!-- 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. 配置文件
默认整个类路径全扫描
java
@Configuration
public class OpenApiConfig {
@Bean
public 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 类为单位
java
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/v1")
@Tag(name = "xxx")
public class xxxController {
}
3.2 Operation 注解
对接口进行描述,一个目标方法为单位
java
@PostMapping("/create")
@Operation(summary = "创建一个 XXX")
public SystemJsonResponse<CustomClass> createXXX() {
}
3.3 Parameter 与 Header 注解
Parameter 描述一个接口的参数与路径参数,Header 描述一个接口的请求头,他们作用于目标方法的形参
java
@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,否则会被标注只读或只写,如果都没有则直接忽略,如果一个数据模型属性都没有,忽略这个数据模型,复杂点的情况还会出现莫名其妙的现象
总而言之规范地写就没问题,框架也没义务和精力去控制各种奇奇怪怪地情况,我们也没必要总结
java
@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 功能还是太弱了
java
@SchemaProperty(name = "ID")
private Long id;
3.6 Hidden
作用于字段,表示忽略字段
java
@Hidden
private String nickname;
3.7 nullable = true
注解参数设置这个代表参数可以为 null
java
@Schema(description = "昵称", nullable = true)
private String nickname;
3.8 响应的数据模型
OpenAPI 提供了 @ApiRespnse 注解,但是很不方便,不如直接去 Postman 或者 Apifox 上进行操作,理想状态就是直接扫描出「请求body对象」和「响应body对象」 Schema 注解描述的数据模型
请求的话,作为参数是类型是确定的,OpenAPI 框架自然是扫描的到的,但是响应的数据模型,一般是统一响应格式的:
java
@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 数据提供给框架
你很容易想到用范型来定义统一响应:
java
@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;
}
但是实践这个方式,你会发现生成的接口文档,data 仍然是 object
其实原因很简单,用 @Schema 将 SystemJsonResponse 描述作一个固定的数据模型,那每个以此对象为返回值的目标方法,接口文档都直接使用这个数据模型
而泛型在定义的时候,本质还是 Object
解决方案也很简单,去掉 @Schema 即可 ,这样框架扫描目标方法返回的 SystemJsonResponse<CustomClass>
的时候,都会创建一个新的数据模型,这个时候就可以通过泛型类型确定准确的响应数据模型了,若存在一个一模一样的才会复用
注意:
- 不支持通配符:
SystemJsonResponse<?>
SystemJsonResponse<? extends CustomClass>
,则仅仅扫描 CustomClass
3.9 补充
GetMapping 的接口,RequestBody 会被扫描成 queryString,而不是 json
4. 访问
http://[host]:[post]/swagger-ui/index.html
http://[host]:[post]/v3/api-docs
更多细节需要去查去探索这里不一一罗列