62

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)
dur
  • 15,689
  • 25
  • 79
  • 125
Kalpesh Soni
  • 6,879
  • 2
  • 56
  • 59

2 Answers2

150

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

nabster
  • 1,561
  • 2
  • 20
  • 32
brianbro
  • 4,141
  • 2
  • 24
  • 37
  • 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… – user3046582 Mar 26 '20 at 17:39
  • Is there an example of replacing a Docket directModelSubstitute such as: `new Docket(...).directModelSubstitute(LocalDateTime.class, Integer.class)`? – IcedDante Jan 18 '22 at 18:20
  • 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 https://springdoc.org/#migrating-from-springfox – Nanotron Jun 15 '23 at 07:15
17

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)

Petr Aleksandrov
  • 1,434
  • 9
  • 24