SpringFox to SpringDoc - migrate Dockets

[nmck257]

What problem are you trying to solve?

SpringFox to SpringDoc migration guide:
https://springdoc.org/#migrating-from-springfox

• rearranging springdoc/openapi recipes. individual springdoc upgrades … #579
  added support for the SB 2.6 recipe to include the dependency changes and the Swagger 2 -> OpenAPI 3 changes.

This issue tracks the pending work to also migrate Docket declarations to SpringDoc replacements (OpenApi / properties / GroupedOpenApi).

Are you interested in contributing this recipe to OpenRewrite?

Maybe eventually but another person is welcome to pick it up

[timtebeek]

In particular I like this perhaps simpler approach

If you have only one Docket — remove it and instead add properties to your application.properties:

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

That might be served with a ScanningRecipe that looks if there really is only a single Docket, and then adds those properties. Does that fit your typical usage there?

[nmck257]

Yeah, I believe it was valid to use SpringFox with zero Docket beans, and in that case the existing recipes should be fine.

For one Docket bean, do exactly what you described. For multiple, refactor to GroupedOpenApi beans.

[Jenson3210]

Hi,

We are looking at this recipe requirement also.
Is there any existing ongoing work?
If I summarize the progress:

• Migrate dependencies for no-docket setup
• Migrate single Docket to properties
• Migrate multiple Docket beans to GroupedOpenApi

sidenote: We have Docket.globalOperationParameters(...) and Docket.directModelSubstitute(...) usages which would require SpringDocUtils.getConfig(). How would we go around this in the single Docket -> Properties approach. Or even in the multiple Docket. I do not have internall experiences/examples of this so hoping someone here would have a good example.

[nmck257]

hey @Jenson3210 -- yep, I don't have any work in progress, so contribution from you would be excellent!

The summary sounds accurate. For the Docket methods you mentioned, my first thought would be something like this:

• Write a ScanningRecipe which scans to determine if 1) there is only one Docket and 2) the Docket doesn't use any fancy config like that. If both conditions pass, then the edit phase can swap to the properties / autoconfig pattern
• Write a regular Recipe which transforms any and all Dockets to GroupedOpenApi instances (a first draft of this could also bail out on those fancy config methods; I expect the most common config methods would also have trivial replacements in SpringDoc)
• From yaml, call the ScanningRecipe first and the regular Recipe after

Finally, someone would probably need to review each instance method for building Dockets and identify the replacement (if one exists) in SpringDoc. At a glance, it looks like globalOperationParameters has an instance-level replacement in SpringDoc: https://springdoc.org/#how-can-i-set-a-global-header
...but directModelSubstitute might only be controlled at the static / global level in SpringDoc, with that SpringDocUtils class. That could leave us without an "objective" answer for how it should be replaced (imagining an app where one Docket has configured a substitute but another Docket has not), in which case, we'd make an educated guess about which option would be best for the most users, while abiding by the "do no harm" tenet.