SpringdocCompatPlugin

SpringdocCompatPlugin fixes compatibility issues in OpenAPI documents generated by SpringDoc that do not conform to the OpenAPI specification.

In some versions, SpringDoc outputs non-compliant structures that cause parsing and validation failures. SpringdocCompatPlugin automatically fixes these issues during the beforeValidate stage:

• Flatten nested extensions: SpringDoc nests extension fields (like x-*) inside an extra extensions object instead of placing them directly on the parent object. The plugin recursively flattens them back into their parent objects.
• Fill missing parameter schema: SpringDoc sometimes generates parameters without a schema field (and no content defined), which violates the OpenAPI specification. The plugin automatically adds schema: {} to these parameters.

Configuration

.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()],
})

tip

If you encounter any of the following errors during validation, your OpenAPI document was generated by SpringDoc and has compatibility issues — adding this plugin will resolve them:

• "Property extensions is not expected to be here"
• Validation errors caused by parameters missing schema

Options

Option	Type	Default	Description
ensureJsonBody	boolean	false	Deprecated: Use rendering.emptyJsonRequestBodyMode: 'empty-object' instead. Ensure application/json requests always carry a body

ensureJsonBody

Deprecated

This option has been replaced by rendering.emptyJsonRequestBodyMode. Use rendering.emptyJsonRequestBodyMode: 'empty-object' to achieve the same effect.

.keqrc.ts

import { defineKeqConfig } from "@keq-request/cli"

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    userService: "./user-service-swagger.json",
  },
  rendering: {
    emptyJsonRequestBodyMode: 'empty-object', // [!code highlight]
  },
})

rendering.emptyJsonRequestBodyMode also supports additional options: 'strict', 'omit', 'null'. See the configuration docs for details.

Historical notes (deprecated usage)

Spring Boot uses Jackson as the default JSON deserializer. When a request has Content-Type: application/json but carries no body, Jackson throws an error. With ensureJsonBody enabled, the generated code automatically sends an empty object {}.

.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 })],
})