web-dev-qa-db-fra.com

Migration de Springfox Swagger2 vers Springdoc Openapi

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

Essayer de suivre ces

Comment gérer les annotations comme

@ApiModel(value = "Response container")

@ApiModelProperty(value = "Iventory response", required = true)
swagger-2.0openapispringdoc
6
Kalpesh Soni

Vous pouvez mettre à jour les annotations Swagger2 vers Swagger3 (pris en charge par springdoc).

Article avec des expressions rationnelles utiles: https://www.david-merrick.com/2017/11/15/useful-regexes-for-transitioning-swagger-2-0-to-3-0-annotations/

Tous les deux @ApiModel et @ApiModelProperty doit être remplacé par @Schema (io.swagger.v3.oas.annotations.media.Schema)

2
Petr Aleksandrov

Migration depuis SpringFox

  • Supprimez les dépendances springfox et swagger 2. Ajoutez plutôt la dépendance springdoc-openapi-ui.
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-ui</artifactId>
      <version>@springdoc.version@</version>
   </dependency>

  • Remplacez les annotations swagger 2 par des annotations swagger 3 (elles sont déjà incluses avec la dépendance springdoc-openapi-ui). Le package pour les annotations swagger 3 est io.swagger.v3.oas.annotations.

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

  • Cette étape est facultative: Uniquement si vous avez plusieurs Docket beans les remplacer par GroupedOpenApi beans.

    Avant:

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

Maintenant:

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

Si vous n'en avez qu'une seule Docket - supprimez-la et ajoutez des propriétés à votre application.properties:

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**
  • Ajoutez un bean de type OpenAPI. Voir l'exemple:
    @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"));
    }
2
brianbro