Spring boot : Migrating from Springfox Swagger 2 to Springdoc OpenAPI 3

3 min readAug 1, 2020

As we know documentation is an essential part of building REST APIs. I have been using Springfox for my Spring boot projects for quite a while now. The more I kept reading about Open API 3 specifications it was evident that I had to migrate to Open API 3 for REST API documentation. You can find out what’s new in Open API 3 here. One of the important features I personally liked was enhanced security definitions and flexibility to define multiple flows for security schemes.

What are the current options?

Well, there was no update from Springfox about the Open API 3 support until very recently. You can see the discussions about it here. I had to search for alternate solutions and I came across Springdoc library. There are ample amount of implementations available but Springdoc sufficed my needs.

What are the key things to do while migrating from Springfox?

Although migration doc covers most of the things, here are some additional key things to remember while migrating.

1. You will have to remove springfoxand swagger 2 dependencies and add a springdoc-openapi-ui dependency.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>${latest.version}</version>
</dependency>

2. Replace some key annotations with swagger 3 annotations. Like below :

@Api by @Tag
@ApiIgnore by @Hidden
@ApiResponse(code = 404, message = "foo") by @ApiResponse(responseCode = "404", description = "foo") :
Well you don’t have to encapsulate @ApiResponse within @ApiResponses anymore.

3. Replace your Docket beans with GroupedOpenApi beans

GroupedOpenApi allows you to group your APIs based on packages, paths, etc. You can then select it from swagger-ui by selecting a respective definition. Also, GroupedOpenApi is much cleaner than Docket beans.

    @Bean
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
                .group("public-apis")
                .pathsToMatch("/**")
                .pathsToExlude("/actuator/**")
                .build();
    }
  
    @Bean
    public GroupedOpenApi actuatorApi() {
        return GroupedOpenApi.builder()
                .group("actuators")
                .pathsToMatch("/actuators/**")
                .build();
    }

4. Add a bean of type OpenAPI.

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI();
    }

You can customize your OpenAPI bean by adding additional parameters. Most importantly you’ll need to add security schemes as per your needs. For example, if you are using OAuth2 implicit flow along with Authorization token in the header of each request you can define it as :

OAuthFlow oAuthFlow = new OAuthFlow();
oAuthFlow.authorizationUrl(authorizationUrl);return new OpenAPI()
    .components(new Components().addSecuritySchemes(“OAuth”, new SecurityScheme()
    .type(Type.OAUTH2)
    .scheme(“bearer”)
    .bearerFormat(“jwt”)
    .in(In.HEADER)
    .name(“Authorization”)
    .flows(new OAuthFlows()
    .implicit(oAuthFlow))))
    .addSecurityItem(new SecurityRequirement().addList(“OAuth”));

I had a tough time figuring out how to include Authorization token in each request, so key thing is to add a SecurityRequirement and it will automatically include token in each request. You can have various flows depending upon your requirements. Also, do not forget to add springdoc-openapi-security dependency

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>${latest.version}</version>
</dependency>

5. Update your WebSecurity bean of Security Configuration; replace access to swagger 2 api docs by version 3 :

web
    .ignoring()
    .antMatchers(“/”)
    .antMatchers(“/swagger/**”,”/swagger-ui/**”,”/swagger-  ui.html”,”/webjars/**”,”/swagger-resources/**”,”/configuration/**”,”/v3/api-docs/**”);

6. To enable Spring Data Rest support, i.e. support for Pageable types you can add springdoc-openapi-data-rest dependency.

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-data-rest</artifactId>
    <version>${latest.version}</version>
</dependency>

I guess that’s pretty much it! You can also check out the official sample demo projects, for microservices documentation, etc.

Spring boot : Migrating from Springfox Swagger 2 to Springdoc OpenAPI 3

What are the current options?

What are the key things to do while migrating from Springfox?

References :

Written by Deepak Shinde

No responses yet