从Springfox Swagger 2迁移到Springdoc开放API

Question

我试着遵循以下几点：

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

如何处理注释，如：

• @ApiModel（value="响应容器"）
• @ApiModelProperty（value=Iventory响应，必需=true）

Answer 1

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

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

@ApiModel和@ApiModelProperty都需要替换为@架构（io.swagger.v3.oas.annotations.media.架构）

Answer 2

• 删除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-

此步骤是可选的：仅当您有多个Docketbean时，才使用groupedepanpibean替换它们。

之前：

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

定制招摇过市用户界面

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