springdoc-openapi v3.1.1 released!

Security

• GHSA-6f5m-mhjg-qwxq – MCP tool callbacks do not encode path parameters, allowing request retargeting
• GHSA-4v2q-56v7-2cpw – MCP transport, admin and dashboard endpoints are exposed by default
• GHSA-m4cg-mhpg-rh2r – MCP audit events record credentials and request/response bodies without redaction
• GHSA-5f9r-4mc4-qh3c – Unbounded MCP pending-confirmation store allows memory exhaustion
• GHSA-jcgg-59c8-w4wh – MCP request context in a ThreadLocal can leak headers between concurrent WebFlux requests
• GHSA-rhhx-6j8h-8cvw – Unbounded per-locale OpenAPI cache allows memory exhaustion via Accept-Language
• GHSA-c925-vm88-mpp9 – Scalar starters trust client-supplied forwarded headers and render from a shared mutable bean
• CVE-2026-75838 – Cross-site scripting in the DOMPurify bundled with swagger-ui, addressed by upgrading swagger-ui to 5.32.14

Added

• #3340 – Describe JsonNullable values without their Java wrapper
• #3325 – Manage the swagger artifacts in springdoc-openapi-bom, so that modules holding only the annotations stay in lockstep
• #3321 – Add springdoc.login-endpoint.username-example and springdoc.login-endpoint.password-example to document the Spring Security login endpoint

Changed

• MCP is now opt-in. Set springdoc.ai.mcp.enabled=true, and springdoc.ai.mcp.dashboard-enabled=true for the dashboard
• The Scalar starters no longer register forwarded-header handling. Set server.forward-headers-strategy=framework (or native) behind a trusted proxy
• Add springdoc.cache.max-entries (default 100) to bound the per-locale OpenAPI cache
• Add springdoc.ai.mcp.audit.redact (default true) to mask secrets in MCP audit events
• Document that the MCP approval flow is a confirmation step, not an authorization control
• Document the security policy and the release versioning scheme
• #3351 – java.time.Duration, LocalTime and OffsetTime are now resolved by swagger-core instead of being forced to a bare string, so they carry a format (duration and partial-time respectively for the first two)
• A property whose type only implements Set indirectly (LinkedHashSet, TreeSet, …) is now described with uniqueItems: true, following swagger-api/swagger-core#5265
• Upgrade swagger-core to version 2.2.55
• Upgrade swagger-ui to version 5.32.14

Fixed

• #3328, #3337 – /v3/api-docs fails with a NullPointerException when spring-hateoas is on the classpath without HateoasProperties
• #3314 – Json Processing Exception occurred is logged for every constrained parameter whose schema is not a JsonSchema
• #3317 – An injected HttpHeaders parameter is described as a schema
• #3332 – The properties a Kotlin entity inherits from an @Embeddable are missing from the Spring Data REST schemas
• #3320 – @Order and Ordered ignored when applying customizers
• #3319 – A Page nested in another schema is not replaced by PagedModel
• #3313 – Springdoc auto-configurations rely on unspecified auto-configuration ordering
• #3331 – Validation annotations declared inside Optional parameters are dropped
• #3322 – Validation annotations on a container's type argument leak between parameters
• #3315 – An OAS 3.1 JsonSchema cannot be cloned through JSON
• #3300 – TYPE_USE annotations on @ParameterObject fields are not passed along
• #3341 – Stabilize Spring Data Sort and Pageable schema property order
• #3338 – Kotlin nullability interpretation of the Any? type
• #3136 – A Spring Data REST association to a non-exported entity expands its @EmbeddedId and @MapsId fields recursively in the response schemas
• The Spring Data REST response post-processing rewrote an association property in place, so the …Response refs could leak into the schema shared with the request body representation

New Contributors

• @king-407 made their first contribution in #3330
• @jjh75607 made their first contribution in #3335
• @kuglo made their first contribution in #3342
• @kdelay made their first contribution in #3316
• @exijn made their first contribution in #3334

Full Changelog: v3.1.0...v3.1.1

springdoc-openapi v2.9.1 released!

Security

• GHSA-rhhx-6j8h-8cvw – Unbounded per-locale OpenAPI cache allows memory exhaustion via Accept-Language
• GHSA-c925-vm88-mpp9 – Scalar starters trust client-supplied forwarded headers and render from a shared mutable bean
• CVE-2026-75838 – Cross-site scripting in the DOMPurify bundled with swagger-ui, addressed by upgrading swagger-ui to 5.32.14

Added

• #3340 – Describe JsonNullable values without their Java wrapper
• #3325 – Manage the swagger artifacts in springdoc-openapi-bom, so that modules holding only the annotations stay in lockstep
• #3321 – Add springdoc.login-endpoint.username-example and springdoc.login-endpoint.password-example to document the Spring Security login endpoint

Changed

• The Scalar starters no longer register forwarded-header handling. Set server.forward-headers-strategy=framework (or native) behind a trusted proxy
• Add springdoc.cache.max-entries (default 100) to bound the per-locale OpenAPI cache
• Document the security policy and the release versioning scheme
• #3351 – java.time.Duration, LocalTime and OffsetTime are now resolved by swagger-core instead of being forced to a bare string, so they carry a format (duration and partial-time respectively for the first two)
• A property whose type only implements Set indirectly (LinkedHashSet, TreeSet, …) is now described with uniqueItems: true, following swagger-api/swagger-core#5265
• Upgrade swagger-core to version 2.2.55
• Upgrade swagger-ui to version 5.32.14

Fixed

• #3320 – @Order and Ordered ignored when applying customizers
• #3319 – A Page nested in another schema is not replaced by PagedModel
• #3313 – Springdoc auto-configurations rely on unspecified auto-configuration ordering
• #3331 – Validation annotations declared inside Optional parameters are dropped
• #3322 – Validation annotations on a container's type argument leak between parameters
• #3315 – An OAS 3.1 JsonSchema cannot be cloned through JSON
• #3314 – Json Processing Exception occurred is logged for every constrained parameter whose schema is not a JsonSchema
• #3300 – TYPE_USE annotations on @ParameterObject fields are not passed along
• #3341 – Stabilize Spring Data Sort and Pageable schema property order
• #3338 – Kotlin nullability interpretation of the Any? type
• #3332 – The properties a Kotlin entity inherits from an @Embeddable are missing from the Spring Data REST schemas
• #3136 – A Spring Data REST association to a non-exported entity expands its @EmbeddedId and @MapsId fields recursively in the response schemas
• The Spring Data REST response post-processing rewrote an association property in place, so the …Response refs could leak into the schema shared with the request body representation
• #3317 – Ignore an injected HttpHeaders parameter explicitly. The reported failure needs Spring Framework 7, where HttpHeaders stopped implementing MultiValueMap; on this line it is still covered by the Map entry of the ignore list, so this is regression cover rather than a behaviour change
• Harden the Spring Data REST response post-processing against an _embedded schema that carries no properties

New Contributors

• @tthornton3-chwy made their first contribution in #3300

Full Changelog: v2.9.0...v2.9.1

springdoc-openapi v3,1,0 released!

What's Changed

• Fix request-specific Swagger UI index transformations by @limehee in #3279
• Fix #3282: preserve nest() version predicate across all routes in nest by @seonwooj0810 in #3296
• Upgrade Spring Boot to version 4.1.0
• Upgrade Spring AI to version 2.0.0
• Upgrade swagger-core to version 2.2.52
• Upgrade swagger-ui to version 5.32.11
• #3307 – Act upon SonarQube warnings
• #3306 – Act upon SonarQube warnings

Added

• #3269 – Add mechanism to disable nullable for Kotlin properties
• Allow request-specific Swagger UI index transformation

Fixed

• #3304 – Kotlin parent class's field is not properly marked as nullable
• #3294 – Duplicated path getting swagger-config
• #3293 – Inconsistent OpenAPI schema naming with SNAKE_CASE: some Java record fields remain camelCase
• #3292 – Make WebProperties and WebMvcProperties optional in SwaggerConfig
• #3284 – Upgrade swagger-core from version 2.2.48 to 2.2.49
• #3282 – Preserve version from nest() predicate across all routes in nest
• #3281 – Stabilize Spring Data Page schema property order
• #3274 – Description disappears from the generated json after upgrade to 3.0.3
• #3270 – Validation annotation of ParameterObject property applied to PathVariable with the same name, even in unrelated endpoints
• #3266 – Upgrade swagger-core from version 2.2.47 to 2.2.48
• #3263 – Null key for a Map not allowed in JSON

Full Changelog: v3.0.3...v3.1.0

springdoc-openapi v2.9.0 released!

What's Changed

• Fix version mismatch in springdoc-openapi-tests: update sub-modules to 2.8.18-SNAPSHOT by @ankushsurani in #3262
• Upgrade swagger-core from version 2.2.47 to 2.2.48 by @Mattias-Sehlstedt in #3266
• Add mechanism to disable nullable for Kotlin properties by @0xabadea in #3269
• Stabilize Spring Data Page schema property order by @dpkass in #3281
• Upgrade swagger-core from version 2.2.48 to 2.2.49 by @Mattias-Sehlstedt in #3284
• Fix vulnerabilities: upgrade spring boot to 3.5.14 and swagger-ui to 5.32.5 by @Axel-1 in #3291

• Make WebProperties and WebMvcProperties optional in SwaggerConfig by @seonwooj0810 in #3292
• chore: act upon SonarQube warnings by @Mattias-Sehlstedt in #3306

• Upgrade Spring Boot to version 3.5.16
• Upgrade swagger-core to version 2.2.52
• Upgrade swagger-ui to version 5.32.11
• Upgrade commons-lang to version 3.20.0
• Act upon SonarQube warnings (#3306, #3307)

Added

• Allow request-specific Swagger UI index transformation
• Add a mechanism to disable nullable for Kotlin properties

Fixed

• #3304 – Kotlin parent class's field is not properly marked as nullable
• #3298 – Update Spring Boot to 3.5.16
• #3294 – Duplicated path getting swagger-config
• #3293 – Inconsistent OpenAPI schema naming with SNAKE_CASE: some Java record fields remain camelCase
• #3291 – Fix vulnerabilities: upgrade Spring Boot to 3.5.14 and swagger-ui to 5.32.5
• #3288 – Make WebProperties and WebMvcProperties optional in SwaggerConfig
• #3281 – Stabilize Spring Data Page schema property order
• #3274 – Description disappears from the generated JSON after upgrade to 3.0.3
• #3270 – Validation annotation of ParameterObject property applied to PathVariable with the same name, even in unrelated endpoints
• #3263 – Null key for a Map not allowed in JSON
• #3262 – Fix version mismatch in springdoc-openapi-tests modules

New Contributors

• @ankushsurani made their first contribution in #3262
• @0xabadea made their first contribution in #3269
• @dpkass made their first contribution in #3281
• @Axel-1 made their first contribution in #3291

Full Changelog: v2.8.17...v2.9.0

springdoc-openapi v3.0.3 released!

Added

• #3246 – Add Springdoc OpenAPI MCP (Model Context Protocol) support
• #3256 – Auto-set nullable: true for Kotlin nullable types in schema properties
• #3239 – Add support for the @Range constraint validation annotation
• #3244 – Handle default values for LocalDate

Changed

• Upgrade Spring Boot to version 4.0.5
• Upgrade swagger-core to version 2.2.47
• Upgrade swagger-ui to version 5.32.2
• #3260 – @ConditionalOnClass(HateoasProperties.class) in SpringDocHateoasConfiguration
• Forwards all MCP non-transport headers to downstream methods
• Dynamically resolve the base path from window.location.pathname for MCP UI

Fixed

• #3258 – Setting API Version Required when using WebFlux breaks the Swagger UI
• #3259 – Annotated Generic properties getting applied to sibling properties
• #3255 – Direction enum: fixed visibility scope of group order so that setGroupsOrder method can be used
• #3247 – Preserve YAML group URLs in Swagger UI
• #3245 – Upgrade swagger-core from version 2.2.43 to 2.2.45
• #3235 – PropertyResolverUtils retains a JsonNode when reading an ExtensionProperty annotation
• #3226 – Propagate JsonView context when resolving Page<T> schema

New Contributors

• @seregamorph made their first contribution in #3260

Full Changelog: v3.0.2...v3.0.3

springdoc-openapi v2.8.17 released!

Added

• Add support for the @Range constraint validation annotation
• Auto-set nullable: true for Kotlin nullable types in schema properties

Changed

• Upgrade Spring Boot to version 3.5.13
• Upgrade swagger-core to version 2.2.47
• Upgrade swagger-ui to version 5.32.2

Fixed

• #3259 – Fix an issue with annotated types with generics on parameters
• #3255 – Handle $ref nullable wrapping and OAS 3.1 support
• #3245 – Upgrade swagger-core from 2.2.43 to 2.2.45 (fixes schema resolution issues)
• #3241 – Generic error responses from multiple @ControllerAdvice are still nondeterministic across OS
• #3236 – Preserve YAML group URLs in Swagger UI
• Fix PropertyResolverUtils to retain a JsonNode when reading an ExtensionProperty annotation
• Fix handling of default values for LocalDate

New Contributors

• @soowanx made their first contribution in #3247
• @pcalouche made their first contribution in #3254
• @sisco70 made their first contribution in #3255
• @thejeff77 made their first contribution in #3256
• @mcclellanmj made their first contribution in #3259

Full Changelog: v2.8.16...v2.8.17

springdoc-openapi v3.0.2 released!

Added

• #3229 – Add support for Spring Framework API Versioning with Functional Endpoints
• #3208 – Add springdoc.swagger-ui.document-title property

Changed

• Upgrade Spring Boot to version 4.0.3
• Upgrade swagger-core to version 2.2.43
• Upgrade swagger-ui to version 5.32.0
• Upgrade Scalar to version 0.5.55

Fixed

• #3232 – Gracefully handle springdoc endpoint paths during API version resolution
• #3230 – Scalar source URLs resolve to null/<groupName> on second request when using GroupedOpenApi
• #3228 – springdoc-openapi-starter 3.x doesn't depend on org.springframework.boot:spring-boot-starter
• #3220 – Reachability metadata not compatible with GraalVM 25
• #3195 – Application won't compile when OpenApi and spring-boot-data-rest is present
• #3193 – OpenApi field in SpringDocConfigProperties does not comply with camel case naming conventions
• #3215 – Type annotation not considered when Kotlin is not present
• #3199 – Prevent duplicate _links in allOf child schemas
• #3198 – Property resolution for parameter default values
• #3206 – Upgrade swagger-core from version 2.2.41 to 2.2.42

Full Changelog: v3.0.1...v3.0.2

springdoc-openapi v2.8.16 released!

Added

• #3208 - Add support for springdoc.swagger-ui.document-title property to customize the browser tab title

Changed

• Upgrade Spring Boot to version 3.5.11
• Upgrade swagger-core to version 2.2.43
• Upgrade swagger-ui to version 5.32.0
• Upgrade Scalar to version 0.5.55

Fixed

• #3230 – Scalar source URLs resolve to null/<groupName> on second request when using GroupedOpenApi
• #3226 – Propagate @JsonView context when resolving Page<T> schema in PageOpenAPIConverter
• #3205 – springdoc-ui does not work with native compile GraalVM 25
• #3219 – Upgrade swagger-core from 2.2.42 to 2.2.43 (fixes schema resolution issues)
• #3193 – OpenApi field in SpringDocConfigProperties does not comply with camelCase naming conventions
• #3161 – Prevent duplicate _links in allOf child schemas extending RepresentationModel
• Fix type annotation not considered when Kotlin is not present
• Fix property resolution for parameter default values

What's Changed

• Update CONTRIBUTING.adoc by @gwr0-0 in #3209
• Upgrade swagger-core from version 2.2.41 to 2.2.42 by @Mattias-Sehlstedt in #3206
• Fix Gradle dependencies in README by @minseo6753 in #3190
• Fix: Property resolution for parameter default values by @Mattias-Sehlstedt in #3198
• fix(#3161): Prevent duplicate _links in allOf child schemas by @huisoo in #3199
• feat(swagger-ui): add springdoc.swagger-ui.document-title property by @ardaaltinors in #3208
• docs: fix typos and correct Gradle artifact IDs by @vidya381 in #3211
• fix: add so that the type annotation is considered again if kotlin is not present by @Mattias-Sehlstedt in #3215
• Improve README by @bwaldvogel in #3217
• Upgrade swagger-core from version 2.2.42 to 2.2.43 by @Mattias-Sehlstedt in #3219
• fix: propagate JsonView context when resolving Page schema by @Akila-1329 in #3226

New Contributors

• @gwr0-0 made their first contribution in #3209
• @minseo6753 made their first contribution in #3190
• @huisoo made their first contribution in #3199
• @ardaaltinors made their first contribution in #3208
• @vidya381 made their first contribution in #3211
• @bwaldvogel made their first contribution in #3217
• @Akila-1329 made their first contribution in #3226

Full Changelog: v2.8.15...v2.8.16

springdoc-openapi v3.0.1 released!

Added

• #3122 – Add log notifications when SpringDocs / Scalar are enabled by default
• #3123 – Add support for serving static resources
• #3151 – Add @Order to ApplicationReadyEvent listener
• #3158 – Add support for API groups in Scalar
• #3187 – Add Scalar WebMVC and WebFlux support
• #3185 – Disable creation of blank GitHub issues (GitHub settings & workflow)
• #3186 – Decouple Web Server APIs following Spring Boot modularization
• #3131 – Improve warning messages when documentation is explicitly enabled
• #3183 – Remove unused operations consumer from route builder methods
• #3141 – Change handling so useReturnTypeSchema is evaluated at HTTP status code level instead of method level

Changed

• Upgrade Spring Boot to version 4.0.1
• Upgrade swagger-core to version 2.2.41
• Upgrade swagger-ui to version 5.31.0
• Upgrade Scalar to version 0.4.3

Fixed

• #3133 – Fix regression where content type from Swagger @RequestBody did not take precedence
• #3146 – Fix WebJar resource handler mappings for Swagger UI resources
• #3168 – Support @Schema annotations on Kotlin value classes
• #3178 – Fix regression when generating documentation for Kotlin LinkedHashSet
• #3170 – Fix warnings when setting title and description in application.yml
• #3173 – Fix /v3/api-docs returning Base64-encoded response with Spring Framework 7.0.2
• #3155 – Fix native image support regression with SpringDoc 3.0 and Spring Boot 4.0

What's Changed

• Fix WebJar resource handler mappings for Swagger UI resources by @jamesmissen in #3146
• Decoupling Web Server APIs after Spring Boot modularization by @nicolasb29 in #3186

New Contributors

• @jamesmissen made their first contribution in #3146
• @nicolasb29 made their first contribution in #3186

Full Changelog: v3.0.0...v3.0.1

springdoc-openapi v2.8.15 released!

Added

• #3122 – Add log notifications when SpringDocs / Scalar are enabled by default
• #3123 – Add support for serving static resources
• #3151 – Add @Order to ApplicationReadyEvent listener
• #3158 – Add support for API groups in Scalar
• #3187 – Add Scalar WebMVC and WebFlux support
• #3185 – Disable creation of blank GitHub issues (GitHub settings & workflow)
• #3186 – Decouple Web Server APIs following Spring Boot modularization
• #3131 - Improve warning messages when documentation is explicitly enabled
• #3183 - Remove unused operations consumer from route builder methods
• #3141 - Change handling so useReturnTypeSchema is evaluated at HTTP status code level instead of method level

Changed

• Upgrade Spring Boot to version 3.5.9
• Upgrade swagger-core to version 2.2.41
• Upgrade swagger-ui to version 5.31.0
• Upgrade Scalar to version 0.4.3

Fixed

• #3133 – Fix regression where content type from Swagger @RequestBody did not take precedence
• #3146 – Fix WebJar resource handler mappings for Swagger UI resources
• #3168 – Support @Schema annotations on Kotlin value classes
• #3178 – Fix regression when generating documentation for Kotlin LinkedHashSet
• #3170 – Fix warnings when setting title and description in application.yml
• #3187 – Add scalar scalar-webmvc and scalar-webflux support

What's Changed

• feat: static resources by @TiPo4u4eK in #3123
• [Fix] Regression where content type from swagger @RequestBody does not take precedence by @Mattias-Sehlstedt in #3133
• docs(security): allow /v3/api-docs(.yaml) & Swagger UI when Spring Security is enabled (management port) by @RituMalav in #3150
• docs(management-port): add example for /v3/api-docs and Swagger UI (#… by @RituMalav in #3148
• Change so useReturnTypeSchema is considered on an http code level by @Mattias-Sehlstedt in #3141
• feat: add @order to ApplicationReadyEvent listener (#3151) by @WeisSebastian in #3153
• Remove unused operations consumer from route builder methods by @JohnNiang in #3183
• Disable creation of a blank GitHub issue by @Mattias-Sehlstedt in #3185

New Contributors

• @TiPo4u4eK made their first contribution in #3123
• @RituMalav made their first contribution in #3150
• @WeisSebastian made their first contribution in #3153

Full Changelog: v2.8.14...v2.8.15