Как поместить аннотации микропрофиля/OpenAPI в интерфейс для создания Swagger-файла, сохраняя при этом исходный код чист ⇐ JAVA

[Anonymous]

В Quarkus мне нужно определить API, который приведет к созданию JSON/YAML-файла Swagger-UI для передачи потребителям.
Это работает так, как ожидалось/задокументировано путем определения множество аннотаций в REST-конечной точке. Например:
@POST
@Operation(summary = "creates a new product")
@APIResponse(responseCode = "201", description = "product creation successful")
@APIResponse(responseCode = "500", description = "Server unavailable")
@Path("/")
@RequestBody(content = @Content(examples = {
@ExampleObject(
name = CreateProductRequest.EXAMPLE1_NAME,
description = CreateProductRequest.EXAMPLE1_DESCRIPTION,
value = CreateProductRequest.EXAMPLE1_VALUE
)
}))
@APIResponse(content = @Content(examples = {
@ExampleObject(
name = CreateProductResponse.EXAMPLE1_NAME,
description = CreateProductResponse.EXAMPLE1_DESCRIPTION,
value = CreateProductResponse.EXAMPLE1_VALUE
)
}))
@ResponseStatus(201)
public CreateProductResponse create(CreateProductRequest createProductRequest) throws ValidationException {
return productManager.create(new RequestContext(1, 1), createProductRequest);
}

Таким образом конечная точка REST становится почти нечитаемой (это один из небольших примеров).
Мой предпочтительный способ решения этой проблемы: определить интерфейс, который будет реализовывать конечная точка REST.
Может мне как-то помочь...

• ... (а) выясните, возможно ли это вообще.
  
  ... покажите мне пример того, как определить такой интерфейс в Quarkus

[*]... (б) покажите мне лучший способ достичь моей цели - иметь небольшие/обслуживаемые конечные точки REST, сохраняя при этом возможность документировать определение API Swagger-UI, близкое к исходному коду.

То, что я ожидал, будет работать (но не работает, аннотации в интерфейсе полностью игнорируются платформой и не попадают в сгенерированный файл swagger-json/yaml):
@Path("/api/v1/products")
public class ProductControllerV1 implements ProductApiV1 {

@POST
@Path("/")
@Override
public CreateProductResponse create(CreateProductRequest createProductRequest) throws ValidationException {
return productManager.create(new RequestContext(1, 1), createProductRequest);
}
}

@Tag(
name = "Product Controller V1",
description = "Product Operations, for testing many different use-cases"
)
@Path("/api/v1/products")
public interface ProductApiV1 {

@POST
@Operation(summary = "creates a new product")
@APIResponse(responseCode = "201", description = "product creation successful")
@APIResponse(responseCode = "500", description = "Server unavailable")
@Path("/")
@RequestBody(content = @Content(examples = {
@ExampleObject(
name = CreateProductRequest.EXAMPLE1_NAME,
description = CreateProductRequest.EXAMPLE1_DESCRIPTION,
value = CreateProductRequest.EXAMPLE1_VALUE
)
}))
@APIResponse(content = @Content(examples = {
@ExampleObject(
name = CreateProductResponse.EXAMPLE1_NAME,
description = CreateProductResponse.EXAMPLE1_DESCRIPTION,
value = CreateProductResponse.EXAMPLE1_VALUE
)
}))
@ResponseStatus(201)
CreateProductResponse create(CreateProductRequest createProductRequest) throws ValidationException;


Подробнее здесь: https://stackoverflow.com/questions/791 ... ating-swag