从 springfox swagger2 迁移到 springdoc openapi

Question

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

试图遵循这些

我如何处理像这样的注释

@ApiModel(value = "Response container")

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

Answer 1

从 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

• 此步骤是可选的：仅当您有多个 Docketbean 时将它们替换为GroupedOpenApibean。

  前：

      @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 。见示例：

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

• 如果 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-。

Answer 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)