从 Springfox Swagger 2 迁移到 Springdoc Open API

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 2 注释替换为 swagger 3 注释（它已包含在

  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

  豆时，才将其替换为

  GroupedOpenApi

  豆。

  之前：

      @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-。

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

)

Answer 3

旧样式：Springfox swagger 2.x：@ApiModel(value = "响应容器") @ApiModelProperty(value = "库存响应", required = true)

解决方案： （新风格） 对于 Springdoc Open API (swagger 3.x)，请使用 @schema 注释。

例如：

                  @Schema(
                      description = "Pagination with sorting support",
                      type = "Pageable",
                      allowableValues = {
                              "page=0&size=100&sort=name,asc",
                              "page=0&size=100&sort=name,desc"
                      })) Pageable pageable