Linux Swagger API文档如何实现版本兼容性

在Linux环境下使用Swagger实现API文档的版本兼容性，可以通过以下几种方法实现：

1. 基于路径的版本控制

为每个API版本分配不同的路径前缀，例如：

• /api/v1/ 对应版本1的API文档
• /api/v2/ 对应版本2的API文档

示例配置（Spring Boot项目）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket apiV1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.v1"))
                .paths(PathSelectors.ant("/api/v1/**"))
                .build();
    }

    @Bean
    public Docket apiV2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v2")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.v2"))
                .paths(PathSelectors.ant("/api/v2/**"))
                .build();
    }
}

2. 基于查询参数的版本控制

在API请求URL中添加查询参数来指定版本，例如：

http://localhost:58427/api/Values?api-version=2.0

示例配置（Spring Boot项目）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .version("1.0")
                .description("API documentation")
                .build();
    }
}

3. 基于HTTP请求头的版本控制

通过自定义HTTP请求头（例如 X-API-Version）传递版本信息。

示例配置（Spring Boot项目）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .version("1.0")
                .description("API documentation")
                .build();
    }
}

4. 使用OpenAPI 3.0规范

升级Swagger依赖到支持OpenAPI 3.0的版本（例如 swagger-core 2.2.29及以上版本），并在 apiInfo 方法中设置API的标题、版本和描述等信息。

示例配置（Spring Boot项目）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("My API")
                .version("1.0")
                .description("API documentation")
                .build();
    }
}

5. 使用Springfox管理API版本

在 pom.xml 中添加Springfox的依赖，创建多个 Docket 实例，每个实例对应一个API版本，并使用 @RequestMapping 注解为每个版本的API指定不同的路径。

示例配置（Spring Boot项目）：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket apiV1() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v1")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.v1"))
                .paths(PathSelectors.ant("/api/v1/**"))
                .build();
    }

    @Bean
    public Docket apiV2() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("v2")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller.v2"))
                .paths(PathSelectors.ant("/api/v2/**"))
                .build();
    }
}

通过上述方法，可以在Linux环境下使用Swagger有效地管理API的版本兼容问题，确保不同版本的API文档能够正确生成并供前后端开发人员使用。