从 springfox swagger2 迁移到 springdoc openapi [英] Migrating from springfox swagger2 to springdoc openapi

问题描述

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)

推荐答案

从 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.

  • 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) 或 @Operation(hidden = true) 或 @Hidden
    • @ApiModel ->@Schema
    • @ApiModelProperty ->@Schema
    • @ApiParam -> @Parameter
    • @ApiOperation -> @Operation
    • @Api -> @Tag
    • @ApiImplicitParams -> @Parameters
    • @ApiImplicitParam -> @Parameter
    • @ApiIgnore -> @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
    • @ApiModel -> @Schema
    • @ApiModelProperty -> @Schema

    此步骤是可选的:仅当您有多个 Docket bean 时将它们替换为 GroupedOpenApi bean.

    This step is optional: Only if you have multiple Docket beans replace them with 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:

    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/**
    

  • 添加 OpenAPI 类型的 bean.见示例:

  • 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"));
        }
    

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

  • 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.

    自定义 Swagger UI

    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-.

    这篇关于从 springfox swagger2 迁移到 springdoc openapi的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！