disable "/v3/api-docs", and "/swagger-ui.html" by default and upgrade to Scalar 0.2.1

[zakaria-shahen]

Disable SpringDoc by default to maintain alignment with Scalar (scalar/scalar#6781) and ensure that the default configuration follows secure-by-default principles.

[bnasslahsen]

i have merged with the latest version.
We prefer to keep scalar enabled by default.
If someone, is interested to disable it - it can be changed through property.

[zakaria-shahen]

@bnasslahsen

Making it disabled by default would be better. You could introduce a new property like springdoc.scalar.enabled to allow users to enable or disable it, rather than relying on scalar.enabled.

From previous experience, I've found that people typically disable SpringDoc via springdoc.swagger-ui.enabled only in production profiles, without realizing for several months that their other endpoints remain exposed to the internet through /v3/api-docs.

You might say this is a noob mistake, but in reality, the mistake is made by principal-level developers, and it passes both internal and external penetration testing. No one catches it for months in production, until a curious junior developer (me at one of my previous companies) discovers it by accident.

There may still be other systems/companies where this issue hasn't been discovered yet, so it's better to disable it by default and ensure users familiarize themselves with your library before enabling it.

Note that I sent the same concern to Scalar via email, and they accepted it: scalar/scalar#6781 (Of course, I also sent the same concern to SpringDoc via email)

I agree with you that it may seem overkill, but when you look at it from the user's perspective, it makes sense.

Also, in 2024, the CVE board updated the CNA rules, including the following:

• 4.1.4 Insecure default configuration settings SHOULD be determined to be vulnerabilities

So what do you think?

Thank you for your effort in providing the Spring ecosystem with this library which makes our lives easier.

[jimisola]

This change seems like a breaking change. Does not SpringDoc use semantic versioning?

[louis-jaris]

@zakaria-shahen FYI, this PR does not actually disable OpenAPI generation, and SwaggerUI rendering

My setup: springdoc-openapi-starter-webmvc-ui with 2.8.14 -- springdoc.api-docs.enabled and springdoc.swagger-ui.enabled not set anywhere (so falling back on default values).

It looks like instead of changing these properties values like this PR did, you should be changing the matchIfMissing = true into matchIfMissing = false (for example there https://github.com/springdoc/springdoc-openapi/blob/main/springdoc-openapi-starter-webmvc-ui/src/main/java/org/springdoc/webmvc/ui/SwaggerConfig.java#L68)

In other words, it looks like this PR did not do what it was saying.

[zakaria-shahen]

You're right, this PR does two things:

• it upgrades Scalar to version 0.2.1*
• makes SpringDoc disabled by default.

However, @bnasslahsen merged it but only accepted the Scalar upgrade, and Unfortunately then reverted the change that I made to disable SpringDoc and Scalar by default (as per his comment see #3090 (comment))

So, unfortunately yes Scalar (within springdoc only) and Springdoc are still enabled by default

*Because Scalar is disabled by default in after this version. (see scalar/scalar#6781)

@zakaria-shahen FYI, this PR does not actually disable OpenAPI generation, and SwaggerUI rendering

My setup: springdoc-openapi-starter-webmvc-ui with 2.8.14 -- springdoc.api-docs.enabled and springdoc.swagger-ui.enabled not set anywhere (so falling back on default values).

It looks like instead of changing these properties values like this PR did, you should be changing the matchIfMissing = true into matchIfMissing = false (for example there https://github.com/springdoc/springdoc-openapi/blob/main/springdoc-openapi-starter-webmvc-ui/src/main/java/org/springdoc/webmvc/ui/SwaggerConfig.java#L68)

In other words, it looks like this PR did not do what it was saying.

[Leander250]

So this PR (after the additional changes) results only in these two log messages if I am not mistaken:

2025-11-10T21:49:13.074+01:00  WARN 7 --- [backend] [main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /v3/api-docs endpoint is enabled by default. To disable it in production, set the property 'springdoc.api-docs.enabled=false'
2025-11-10T21:49:13.074+01:00  WARN 7 --- [backend] [main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /swagger-ui.html endpoint is enabled by default. To disable it in production, set the property 'springdoc.swagger-ui.enabled=false'

I think it's a good improvement, even though there are many people who ignore warnings.

[zakaria-shahen]

Yes, you'll see two logs in your case. However, if you add either springdoc-openapi-starter-webmvc-scalar or springdoc-openapi-starter-webflux-scalar dependency, you should see three logs instead.

But I hope @bnasslahsen changes his mind and makes it disabled by default, There are similar cases where maintainers have done that, like the Spring team with Spring Actuator properties (after the Volkswagen issue and Spring Boot Actuator misconfiguration)

Really, unready docs exposed to the public internet without review can lead to bigger issues like reverse engineering, knowledge/data leak etc.

So this PR (after the additional changes) results only in these two log messages if I am not mistaken:

2025-11-10T21:49:13.074+01:00  WARN 7 --- [backend] [main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /v3/api-docs endpoint is enabled by default. To disable it in production, set the property 'springdoc.api-docs.enabled=false'
2025-11-10T21:49:13.074+01:00  WARN 7 --- [backend] [main] o.s.core.events.SpringDocAppInitializer  : SpringDoc /swagger-ui.html endpoint is enabled by default. To disable it in production, set the property 'springdoc.swagger-ui.enabled=false'

I think it's a good improvement, even though there are many people who ignore warnings.

[Leander250]

Yes, probably. But if it stays as it is, it should at least be the case that setting the properties to true makes the warnings disappear. Otherwise, there is no way to disable these warnings.