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	Ensure application/json requests always carry a body

ensureJsonBody

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 {}, ensuring that requests won't trigger backend errors even when no body properties are provided.

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

caution

This option is disabled by default because not all Spring Boot projects use Jackson or its default configuration. Only enable it when you confirm that the backend fails on empty bodies.