Migrating from SpringFox

  • Remove springfox and swagger 2 dependencies. Add springdoc-openapi-starter-webmvc-ui dependency instead.

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.7.0</version>
   </dependency>

  • Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-starter-webmvc-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.

    • @Api → @Tag

    • @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden

    • @ApiImplicitParam → @Parameter

    • @ApiImplicitParams → @Parameters

    • @ApiModel → @Schema

    • @ApiModelProperty(allowEmptyValue = true) → @Schema(nullable = true)

    • @ApiModelProperty → @Schema

    • @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

    • @ApiParam → @Parameter

    • @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

  • This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.

Before:

  @Bean
  public Docket publicApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.public"))
              .paths(PathSelectors.regex("/public.*"))
              .build()
              .groupName("springshop-public")
              .apiInfo(apiInfo());
  }

  @Bean
  public Docket adminApi() {
      return new Docket(DocumentationType.SWAGGER_2)
              .select()
              .apis(RequestHandlerSelectors.basePackage("org.github.springshop.web.admin"))
              .paths(PathSelectors.regex("/admin.*"))
              .apis(RequestHandlerSelectors.withMethodAnnotation(Admin.class))
              .build()
              .groupName("springshop-admin")
              .apiInfo(apiInfo());
  }

Now:

  @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }

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/**

  • Add bean of OpenAPI type. See example:

  @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"));
  }