spring - 如何使用 Spring Boot 设置 SpringFox 显示两个(或更多)版本的 Rest API？

Question

我正在尝试弄清楚如何使用 Spring Fox 管理两个(或更多)版本的 API 端点。

为了对我的 API 进行版本控制，我使用 Versioning through content negotiation ，也称为 Versioning using Accept header 。每个端点的版本是使用 header 信息单独控制的。例如，对于版本一，我使用属性 Produces :

@Override
@PostMapping(
        produces = "application/vnd.company.v1+json")
public ResponseEntity<User> createUser(

对于版本二，我使用:

@Override
@PostMapping(
        produces = "application/vnd.company.v2+json",
        consumes = "application/vnd.company.v2+json")
public ResponseEntity<User> createUserVersion2(

我没有对第一个 (v1) 版本使用 consumes，因此如果客户端在调用时仅使用 application/json，则默认情况下将调用第一个版本。

我想在 Swagger UI 上显示两个版本。如何做到这一点？

Answer 1

这很简单。只需为每个版本创建一个 Docket。

示例，第一个版本:

@Bean
public Docket customImplementation(
        @Value("${springfox.documentation.info.title}") String title,
        @Value("${springfox.documentation.info.description}") String description) {

    return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo(title, description, "1.0"))
            .groupName("v1")
            .useDefaultResponseMessages(false)
            .securitySchemes(newArrayList(apiKey()))
            .pathMapping("/api")
            .securityContexts(newArrayList(securityContext())).select()
            .apis(e -> Objects.requireNonNull(e).produces().parallelStream()
                    .anyMatch(p -> "application/vnd.company.v1+json".equals(p.toString())))
            .paths(PathSelectors.any())
            .build();
}

对于版本二:

@Bean
public Docket customImplementationV2(
        @Value("${springfox.documentation.info.title}") String title,
        @Value("${springfox.documentation.info.description}") String description) {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo(title, description, "2.0"))
                .groupName("v2")
                .select()
                .apis(e -> Objects.requireNonNull(e).produces()
                        .parallelStream()
                        .anyMatch(p -> "application/vnd.company.v2+json".equals(p.toString())))
                .build();
}

这里的 secret 是通过products属性过滤可用端点。

Swagger-UI 将在组合上显示两个版本:

此代码需要位于用@Configuration注释的类上。您还需要使用 @EnableSwagger2 启用 Swagger。