[Bug]: swagger-annotations 2.2.45 still emits spurious additionalProperties/contains/unevaluatedItems with "##default" sentinel on response schemas

[thejeff77]

Description

After upgrading from swagger-annotations 2.2.43 to 2.2.45, the generated OpenAPI 3.1.0 spec contains spurious JSON Schema keywords (additionalProperties, contains, unevaluatedItems, items) with "default": "##default" sentinel values on response schemas where they do not belong. This is related to the sentinel change in #5063 (v2.2.44) and the partial fix in #5078 (v2.2.45), but v2.2.45 does not fully resolve the issue.

This is distinct from #5086 (which covers @Parameter + @ArraySchema). This bug affects response body schemas — both $ref schemas and type: array schemas.

Environment

• Spring Boot: 3.5.11
• springdoc-openapi: 2.8.16
• swagger-annotations: 2.2.45 (regression confirmed absent in 2.2.43)
• OpenAPI version: 3.1.0

Reproduction

A standard Spring Boot controller returning a List<T>:

@GetMapping("/v1/items/{item-id}/details")
public ResponseEntity<List<ItemDetailResponse>> getDetails(
    @PathVariable("item-id") String itemId) {
    // ...
}

With swagger-annotations 2.2.43, the generated schema for the 200 response is:

{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ItemDetailResponse"
  }
}

With swagger-annotations 2.2.45, the same endpoint produces:

{
  "type": "array",
  "additionalProperties": {
    "default": "##default"
  },
  "contains": {
    "default": "##default"
  },
  "items": {
    "$ref": "#/components/schemas/ItemDetailResponse",
    "contains": {
      "default": "##default"
    },
    "default": "##default",
    "unevaluatedItems": {
      "default": "##default"
    }
  },
  "unevaluatedItems": {
    "default": "##default"
  }
}

Similarly, endpoints returning a single object via $ref gain extraneous keywords:

{
  "$ref": "#/components/schemas/SomeResponse",
  "additionalProperties": {
    "default": "##default"
  },
  "contains": {
    "default": "##default"
  },
  "default": "##default",
  "items": {
    "default": "##default"
  },
  "unevaluatedItems": {
    "default": "##default"
  }
}

Scale of impact

In our production spec (~250 endpoint Spring Boot service), upgrading to 2.2.45 introduces:

Keyword	Spurious occurrences with ##default
default	1,375
contains	246
unevaluatedItems	246
additionalProperties	242
items	241

Why this breaks downstream tools

The combination of type: array + additionalProperties is semantically invalid — additionalProperties is an object-only keyword. Code generators like Fabrikt interpret additionalProperties as a signal that the schema represents a map/dictionary. When combined with type: array, this creates an impossible type (array + MAP specialization), causing a crash:

java.lang.IllegalStateException: Unknown OAS type: array and format: null 
  and specialization: MAP

Root cause hypothesis

The ##default sentinel introduced in #5063 is not being filtered out in all code paths before schema serialization. PR #5078 addressed the defaultValue merge logic, but the sentinel is still leaking through the sub-schema keywords (additionalProperties, contains, unevaluatedItems, items) that get populated with { "default": "##default" } objects when they should not be present at all.

Expected behavior

Response schemas should not contain any ##default sentinel values or spurious sub-schema keywords that were not explicitly defined in the source annotations. The output with 2.2.45 should match the clean output from 2.2.43.

Workaround

Pin swagger-annotations to 2.2.43.

[Mattias-Sehlstedt]

Note: I am a contributor, not a maintainer, I have no affiliations with this project.

My current understanding is that this is tied to springdoc-openapi and how it introspects and handles Spring Boot 3 endpoints together with the breaking change of introducing the ##default sentinel values.

But since I am unable to reproduce your issue more details are needed regarding your controller definition and the classes involved (the produced schema is what is present in the app22.json).

[ahoehma]

We're hitting this too!

Working Environment:

Dependency	Version
swagger-annotations-jakarta	2.2.43
springdoc-openapi	3.0.1
springdoc-openapi-maven-plugin	1.5
Spring Boot	4.0.4
Jackson	2.21
Java	25

Not Working Environment:

Dependency	Version
swagger-annotations-jakarta	2.2.44 or 2.2.45

Observed behavior:

Every @Parameter(description = "...") without an explicit defaultValue ends up with "##default" as the default value in the generated spec.

Example 1 — required path parameter (a default makes no sense here at all):

Java:

@Parameter(description = "Id of the configuration you would like to read.")
@PathVariable
String configurationId

Generated spec:

{
  "name": "configurationId",
  "in": "path",
  "required": true,
  "schema": { "type": "string", "default": "##default" }
}

Example 2 — optional query parameter where the description documents the real default, making the spec actively misleading:

Java:

@Parameter(description = "Add trace details? If this is false (default) only top-level actions are returned.")
@RequestParam(required = false, defaultValue = "false")
boolean addTrace

Generated spec:

{
  "name": "addTrace",
  "in": "query",
  "required": false,
  "schema": { "type": "string", "default": "##default" }
}

Example 3 — optional query parameter with no default:

Java:

@Parameter(description = "A regexp for versions you would like to filter for. Leave empty to match all.")
@RequestParam(required = false)
String versionRegexp

Generated spec:

{
  "name": "versionRegexp",
  "in": "query",
  "required": false,
  "schema": { "type": "string", "default": "##default" }
}

[OlliL]

Are you all sure you do not have a single swagger dependency still at version 2.2.43 in your classpath while your swagger-annotations-jakarta is at 2.2.45? Have you checked your effective classpath?

I had to exclude all transitive swagger dependencies which where brought in by springdoc because they where still at 2.2.43. And mixing versions is not supported.

[ahoehma]

Good point — I checked my effective classpath. With springdoc-openapi 3.0.1, bumping swagger-annotations-jakarta to 2.2.44 would result in exactly the mix you describe:

• swagger-annotations-jakarta: 2.2.44 (explicit)
• swagger-core-jakarta: 2.2.41 (transitive via springdoc)
• swagger-models-jakarta: 2.2.41 (transitive via springdoc)

Which version did you pin swagger-core-jakarta and swagger-models-jakarta to when you excluded the springdoc transitives — 2.2.45 to match your annotations?

[OlliL]

I went from 2.2.43 over "mixed" 2.2.43+2.2.44 (broken) to a working 2.2.45 for every swagger component I explicitly excluded from springdoc as an explicit dependency. Whatever version you decide - they must all be the same starting with 2.2.44 - before that it was not so important if you had mixed minor versions.

[ahoehma]

I can confirm your theory. With springdoc-openapi 3.0.1, bumping only swagger-annotations-jakarta
to 2.2.44 results in exactly the mix you described:

• swagger-annotations-jakarta: 2.2.44 (explicit)
• swagger-core-jakarta: 2.2.41 (transitive via springdoc)
• swagger-models-jakarta: 2.2.41 (transitive via springdoc)

I reproduced this in an isolated branch: with that mix, ##default appears in all generated specs.

After aligning all three artifacts to 2.2.44 (adding explicit dependencyManagement entries for
swagger-core-jakarta and swagger-models-jakarta to override the springdoc transitives), the
##default values are completely gone: 0 occurrences across all generated specs.

So yes — the root cause is version mixing between swagger-annotations and swagger-core/swagger-models.
The fix is to align all three to the same version.

👍

[alexbaeza]

I ran into the same issues for now my workaround to get it to work again has been pinning the following to 2.2.43 via dependencyManagement Plugin

ext {
    swaggerCoreVersion = '2.2.43' //See: https://github.com/swagger-api/swagger-core/issues/5090
}
dependencyManagement {
    dependencies {
        dependency "io.swagger.core.v3:swagger-annotations-jakarta:${swaggerCoreVersion}"
        dependency "io.swagger.core.v3:swagger-core-jakarta:${swaggerCoreVersion}"
        dependency "io.swagger.core.v3:swagger-models-jakarta:${swaggerCoreVersion}"
    }
}

[daniel-kmiecik]

We have prepared a fix that restores the default value to an empty string. We apologize for the inconvenience.