CODEWITHSUNDEEP
swagger-2.0openapispringdoc
Kalpesh Soni
Kalpesh Soni

Reputation: 7287

Migrating from Springfox Swagger 2 to Springdoc Open API

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:

Upvotes: 72

Views: 108940

Answers (3)

justCurious
justCurious

Reputation: 977

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 the @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

Upvotes: 1

brianbro
brianbro

Reputation: 4809

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:

  • To customise the Swagger UI

  • To hide an operation or a controller from documentation

Upvotes: 179

Petr Aleksandrov
Petr Aleksandrov

Reputation: 1524

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)

Upvotes: 20

Related Questions