如何在 Swagger 文档中区分 API 方法的两个版本？

如何解决如何在 Swagger 文档中区分 API 方法的两个版本？

我有 2 个版本的 API GET 方法，我需要为这两个版本添加 swagger 文档，以便 Swagger UI 可以清楚地显示这两个版本。而且我需要为两个版本的 GET 提供相同的路径 URL。两个 GET 端点的路径 URL 是

/maintenance/exec/book/{id}

两个版本唯一的区别是在V1，路径参数是bookId，在V2，路径参数是bookRefId

目前我已经为两个版本添加了 Swagger 文档，但在 Swagger UI 中，我只能找到 V2 GET url。建议我在 Swagger 文档中的此 API 中显式添加 GET 方法的版本（V1 和 V2）

 @GET
 @Path( "{" + ID_ParaM + "}" )
 @Produces( MediaType.APPLICATION_JSON )
 @Operation( summary = "Get Book" )
 @ApiResponse( responseCode = "200",description = "The requested book.",content = @Content( mediaType = "application/json",schema = @Schema( implementation = BookGet.class ) ) )
 @ApiResponse( responseCode = "404",description = "The requested book cannot be found." )
 Book get( @Parameter( in = ParameterIn.PATH,name = ID_ParaM,required = true,description = "The unique identifier for the book resource.",schema = @Schema( type = "string" )) @PathParam( ID_ParaM ) String bookId)
     throws NotFoundException;

 @GET
 @Path( "{" + ID_ParaM + "}" )
 @Produces( ApiMediaType.API_V2_TYPE )
 @Operation( summary = "Get Book V2" )
 @ApiResponse( responseCode = "200",description = "The requested book V2.",content = @Content( mediaType = "application/vnd.yes.httapi.v2+json",schema = @Schema( implementation = BookV2Get.class ) ) )
 @ApiResponse( responseCode = "404",description = "The requested book resource cannot be found." )
 BookV2 getV2( @Parameter( in = ParameterIn.PATH,schema = @Schema( type = "string" ) ) @PathParam( ID_ParaM ) String refId )
     throws NotFoundException;

解决方法

Swagger 无法满足您的要求。

您需要使用 "/v1/getBook" 和 "/v2/getBook" 进行区分。

Swagger 文档

OpenAPI 将唯一操作定义为路径和 HTTP 方法的组合。这意味着不允许对同一路径使用两个 GET 或两个 POST 方法——即使它们具有不同的参数（参数对唯一性没有影响）。

您可以在官方文档中找到详细的答案

https://swagger.io/docs/specification/paths-and-operations/