Migrating from Springfox Swagger 2 to Springdoc Open API

Question

I try to follow these:

https://www.dariawan.com/tutorials/spring/documenting-spring-boot-rest-api-springdoc-openapi-3/

How do I deal with annotations like:

• @ApiModel(value = "Response container")
• @ApiModelProperty(value = "Iventory response", required = true)

Tobacconist

Similar question for @ApiImplicitParams – Lazarus

Accepted answer either came from or became springdoc.org/#migrating-from-springfox – Pressure

Answer 1

Migrating from SpringFox

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

   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>@springdoc.version@</version>
   </dependency>

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

  • @ApiParam -> @Parameter
  • @ApiOperation -> @Operation
  • @Api -> @Tag
  • @ApiImplicitParams -> @Parameters
  • @ApiImplicitParam -> @Parameter
  • @ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
  • @ApiModel -> @Schema
  • @ApiModelProperty -> @Schema

• 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.*"))
                  .build()
                  .groupName("springshop-admin")
                  .apiInfo(apiInfo());
      }
  

  Now:

      @Bean
      public GroupedOpenApi publicApi() {
          return GroupedOpenApi.builder()
                  .setGroup("springshop-public")
                  .pathsToMatch("/public/**")
                  .build();
      }
  
      @Bean
      public GroupedOpenApi adminApi() {
          return GroupedOpenApi.builder()
                  .setGroup("springshop-admin")
                  .pathsToMatch("/admin/**")
                  .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"));
      }
  

• If the swagger-ui is served behind a proxy:

  • https://springdoc.org/faq.html#how-can-i-deploy-the-doploy-springdoc-openapi-ui-behind-a-reverse-proxy.

• To customise the Swagger UI

  • https://springdoc.org/faq.html#how-can-i-configure-swagger-ui.

• To hide an operation or a controller from documentation

  • https://springdoc.org/faq.html#how-can-i-hide-an-operation-or-a-controller-from-documentation-.

Picoline

Do you have any idea how you can group the api based on annotations? Before (with springfox) I could user springfox.documentation.builders.RequestHandlerSelectors.withClassAnnotation for example… – Dorsey

Is there an example of replacing a Docket directModelSubstitute such as: new Docket(...).directModelSubstitute(LocalDateTime.class, Integer.class)? – Thready

This is just a copy and paste job from official documentation. You would be better served just providing the link to official documentation instead of trying to pass it off as your own. The main reason probably being official documentation would be updated wheras this answer could become stale springdoc.org/#migrating-from-springfox – Kagoshima

Answer 2

You can update Swagger2 annotations to Swagger3 (supported by springdoc).

Article with helpful regexps: https://www.david-merrick.com/2017/11/15/useful-regexes-for-transitioning-swagger-2-0-to-3-0-annotations/

Both @ApiModel and @ApiModelProperty need to be replaced with @Schema (io.swagger.v3.oas.annotations.media.Schema)

Unteach

Answer 3

Old style: Springfox swagger 2.x: @ApiModel(value = "Response container") @ApiModelProperty(value = "Inventory response", required = true)

Solution: (new style) For Springdoc Open API (swagger 3.x), use @schema annotation.

e.g:

                  @Schema(
                      description = "Pagination with sorting support",
                      type = "Pageable",
                      allowableValues = {
                              "page=0&size=100&sort=name,asc",
                              "page=0&size=100&sort=name,desc"
                      })) Pageable pageable

Schonfield