问题描述
我有 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 方法——即使它们具有不同的参数（参数对唯一性没有影响）。
您可以在官方文档中找到详细的答案