Migrating from Springfox to OpenAPI 3 in Spring Boot Application
This blogpost, I would like to share about the migration to OpenAPI 3 in my project application that is built using Java 8 and Spring boot.
I was working in a project that had a very old framework support and JDK. I was taking my free time whenever I find one and then did some upgrade to the core so as to get the application to be on the latest frameworks and get support if any issues.
Why Upgrade?
The reason for upgrade is to facilitate the following
- The application dependencies are up-to-date, meaning that when we face any issue or require any help, people will be able to help (Community support). Though we have support for the deprecated frameworks also from the vibrant community like Stackoverflow.com, better to be with the upgrades
- There might be limitations hindering in building new functionality or extending existing ones with the older versions, so a version upgrade to the latest will be always handy
- There is a learning curve and a good boost for the developers so that they dont get fed up like we still have to stick our hands in the old versions and could not learn anything new
- Lots of performance, security patches and modernisation support can be leveraged
Steps to Migrate
- Remove springfox and swagger 2 dependencies. Add
springdoc-openapi-ui
dependency instead
springdoc-openapi-ui
springdoc-openapi-data-rest -> This is mandatory for exposing REST API
- Replacing the Springfox annotations to suit the latest springdoc annotations. I do not want to copy paste from springdoc, because there might be new updates which might get lost in this blog post, so the link is here.
- In the
Application.java
, where you have the application run method, use the below code snippet with the values suitable for your project descriptions
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.info(new Info().title("SpringShop API")
.description("Spring shop sample application")
.version("v0.0.1")
.license(new License().name("Apache 2.0").url("http://springdoc.org")))
.externalDocs(new ExternalDocumentation()
.description("SpringShop Wiki Documentation")
.url("https://springshop.wiki.github.org/docs"));
}
5. Once this is done, your application is ready to be used with the latest version of springdoc
Now that the URL's are changed, you will have to navigate to below like URL
http[s]://host:port/<appName>/swagger-ui.html
Difficult parts
The main difficulty is when we migrate from the current version of spring fox / swagger-ui 2 to the above mentioned springdoc.
I had to literally update all my APIControllers with the annotation tag changes, with replace in all files helped
Additionally, the response
and the responseContainer
properties are no longer present, so they will have to be removed for sure.
The above steps took me approx 4-5 hrs as there was a lot of places to change and finally able to get the new UI up and running.
Posting here in case it might be of help for someone.
Comments
Post a Comment