To be Reviewed By:
Authors: Patrick Johnson
Status: Draft | Discussion | Active | Dropped | Superseded
Superseded by: N/A
Related: N/A
Problem
Geode uses springfox for API documentation. Currently, the version of springfox we use is old and does not support OpenAPI 3. While there are newer releases that support OpenAPI 3, springfox hasn't had a release since 2020 and appears to be abandoned on GitHub. This means springfox could be including old/potentially vulnerable library dependencies; depending on a stale library is generally a bad situation.
Anti-Goals
This proposal does not intend to significantly change or expand Geode's APIs or remove the @Experimental tag from them.
Solution
I would like to migrate away from springfox and instead use springdoc, which is similar in spirit to springfox, but it is actively developed and released, being most recently released in April of 2022. Like springfox, springdoc is licensed under the Apache 2.0 license.
You can find more information about springdoc here: https://springdoc.org or on their GitHub, here: https://github.com/springdoc/springdoc-openapi
This migration will include support for OpenAPI 3, which has been a stumbling block in the past, however, I have already done the migration and believe it to be successful.
Basically, the changes consist of...
- Replacing springfox-swagger2 and springfox-swagger-ui with springdoc-openapi-ui
- Replacing io.swagger:swagger-annotations with io.swagger.core.v3:swagger-annotations, which requires changing some annotations and packages.
- Add ../swagger-ui/index.html to authorized URLs.
- Modifying the swagger configuration classes to use GroupedOpenApi instead of Docket, etc.
Changes and Additions to Public Interfaces
With the move to OpenAPI 3, the default swagger URL changes from ../swagger-ui.html to ../swagger-ui/index.html. This is configurable, so we can support the old URL as well.
Performance Impact
None.
Backwards Compatibility and Upgrade Path
None.
Prior Art
There have been previous attempts to upgrade to springfox 3.0 have been unsuccessful due to significant changes when moving to OpenAPI 3. Since springfox is not actively developed, upgrading is insufficient anyway.
FAQ
NA
Errata
NA