跳到主要内容

SpringdocCompatPlugin

SpringdocCompatPlugin 用于修复 SpringDoc 生成的 OpenAPI 文档中不符合 OpenAPI 规范的兼容性问题。

SpringDoc 在某些版本中会输出以下不规范的结构，导致解析和校验失败。SpringdocCompatPlugin 在 beforeValidate 阶段自动修正这些问题：

  • 展平嵌套 extensions：SpringDoc 会将扩展字段（如 x-*）嵌套在一个额外的 extensions 对象中，而非直接放置在父对象上。插件会递归地将其展平回父对象。
  • 补充缺失的 parameter schema：SpringDoc 生成的 parameters 有时缺少 schema 字段（且未定义 content），不符合 OpenAPI 规范要求。插件会自动为这些 parameter 补充 schema: {}。

配置方法​

.keqrc.ts
import { defineKeqConfig } from "@keq-request/cli"
import { SpringdocCompatPlugin } from '@keq-request/cli/plugins'

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    userService: "./user-service-swagger.json",
  },
  plugins: [new SpringdocCompatPlugin()],
})
提示

如果你在校验阶段遇到以下错误，说明你的 OpenAPI 文档由 SpringDoc 生成且存在兼容性问题，添加此插件即可解决：

  • "Property extensions is not expected to be here"
  • parameter 缺少 schema 导致的校验错误

选项​

参数类型默认值描述
ensureJsonBodybooleanfalse确保 application/json 请求始终携带 body

ensureJsonBody​

Spring Boot 默认使用 Jackson 作为 JSON 反序列化器。当请求设置了 Content-Type: application/json 但未携带 body 时，Jackson 会直接报错。启用 ensureJsonBody 后，生成的代码会自动发送空对象 {}，确保即使未传递任何 body 属性也不会触发后端错误。

.keqrc.ts
import { defineKeqConfig } from "@keq-request/cli"
import { SpringdocCompatPlugin } from '@keq-request/cli/plugins'

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    userService: "./user-service-swagger.json",
  },
  plugins: [new SpringdocCompatPlugin({ ensureJsonBody: true })], // [!code highlight]
})
警告

此选项默认关闭，因为并非所有 Spring Boot 项目都使用 Jackson 或使用 Jackson 的默认配置。仅在确认后端因空 body 报错时启用。