39

我尝试遵循这些：

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

如何处理如下注释：

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

2 回答 2

89

从 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 时，才用bean 替换它们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/**

  • 添加类型的bean OpenAPI。参见示例：

        @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 在代理后面提供：

  • 自定义 Swagger UI

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

于 2020-01-30T21:49:52.127 回答
14

您可以将 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)

于 2020-01-10T23:44:13.143 回答