如何将 Microprofile / OpenAPI 注释放入接口中以生成 Swagger 文件，同时保持源代码干净

Question

在 Quarkus 中，我需要定义一个 API，它将生成 Swagger-UI JSON/YAML 文件以分发给消费者。

通过在 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 端点将实现该接口。

可以以某种方式帮助我...

• ... (a) 看看这是否可能。
  • ...向我展示如何在 Quarkus 中定义此类接口的示例
• ...(b) 向我展示了一种更好的方法来实现拥有小型/可维护的 REST 端点的目标，同时仍然能够记录靠近源代码的 Swagger-UI API 定义。

我期望能起作用（但没有，界面中的注释被框架完全忽略，并且不会进入生成的 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;

Answer 1

您可以在 REST 控制器中尝试一下吗：

@ApplicationScoped
public class ProductControllerV1 implements ProductApiV1 {

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

维护 OpenApi 文档的另一种方法是使用混合方法。

这意味着：您将

openapi.yml

存储在

src/main/resources/META-INF

中，并使用在带注释的代码中很难完成的内容编辑此文件，并且您可以在代码上添加一些简单的注释，Quarkus 将结合这两个结果（使代码更高优先）。