从 Springfox Swagger 2 迁移到 Springdoc Open API

Posted 2023-03-10

【中文标题】从 Springfox Swagger 2 迁移到 Springdoc Open API

【英文标题】：Migrating from Springfox Swagger 2 to Springdoc Open API

【发布时间】：2020-04-05 01:33:20

【问题描述】：

我尝试遵循这些：

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

我如何处理这样的注释：

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

【问题讨论】：

@ApiImplicitParams 的类似问题

【参考方案1】：

Migrating from SpringFox

删除 springfox 和 swagger 2 依赖项。改为添加 springdoc-openapi-ui 依赖项。

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

用 swagger 3 注释替换 swagger 2 注释（它已经包含在 springdoc-openapi-ui 依赖项中）。 swagger 3 注解的包是io.swagger.v3.oas.annotations。

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

此步骤是可选的：仅当您有多个 Docket beans 将它们替换为GroupedOpenApi beans。

之前：

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

现在：

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

如果您只有一个 Docket -- 将其删除，然后将属性添加到您的 application.properties：

springdoc.packagesToScan=package1, package2
springdoc.pathsToMatch=/v1, /api/balance/**

添加OpenAPI 类型的bean。见例子：

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

如果 swagger-ui 在代理后面提供：

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

自定义 Swagger UI

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

从文档中隐藏操作或控制器

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

【讨论】：

您知道如何根据注释对 api 进行分组吗？之前（使用 springfox）我可以使用 springfox.documentation.builders.RequestHandlerSelectors.withClassAnnotation 例如......

是否有替换 Docket directModelSubstitute 的示例，例如：new Docket(...).directModelSubstitute(LocalDateTime.class, Integer.class)？

【参考方案2】：

您可以将 Swagger2 注释更新为 Swagger3（springdoc 支持）。

带有有用正则表达式的文章： https://www.david-merrick.com/2017/11/15/useful-regexes-for-transitioning-swagger-2-0-to-3-0-annotations/

@ApiModel 和@ApiModelProperty 都需要替换为@Schema (io.swagger.v3.oas.annotations.media.Schema)