主页 / coding / 问题 / 79152520
Accepted
funkrusher
Asked: 2024-11-03 18:41:39 +0800 CST

Quarkus - 如何将 Microprofile / OpenAPI 注释放入用于生成 Swagger 文件的界面，同时保持源代码清洁

  • 772

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

通过在 REST-Endpoint 中定义许多注释，它可以按预期/记录的方式工作。例如：

    @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-Endpoint 几乎变得不可读（这是一个较小的示例）

我解决此问题的首选方法是定义一个 REST-Endpoint 将要实现的接口。

能以某种方式帮助我吗...

  • ...（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;
java

1 个回答

  1. Best Answer

    您可以在 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 会将两种结果结合起来（赋予代码更高的优先级）。

    • 1

相关问题