如何在 OpenAPI YAML 文件中添加 JAX-RS 响应

Question

我有一个 REST 服务，我已经使用 OpenAPI 的 YAML 文件定义了 API 签名。

有点像，

title: Sample Pet Store App
description: This is a sample server for a pet store.
termsOfService: http://example.com/terms/
contact:
  name: API Support
  url: http://www.example.com/support
  email: support@example.com
paths:
  v1/employees/{employeeId}:
    get:
      responses:
        '200':
          content:
            ....

从 YAML 文件中，我使用 OpenAPI generator.

之类的东西生成 API 请求

但是如何在我的 YAML 文件中指定 https://docs.oracle.com/javaee/7/api/javax/ws/rs/core/Response.html？

这就是我希望从我的 Java 代码发送响应的方式。我想知道如何将 this Response object 添加到 OpenAPI 的 YAML？

import javax.ws.rs.core.Response;

@Path("/v1/employees")
public Response getEmployee(String employeeId) {
 
    // ...
 
    return Response
      .status(Response.Status.OK)
      .entity(employee)
      .build();
}

我是 REST API 开发的新手。我 checked the documentation，但无法在 OpenAPI 中找到有关如何添加 Javax 响应的详细信息。

Answer 1

取决于您使用的模板，默认情况下不存在，但您可以创建自定义模板来使用。

here 是可用模板列表。

您必须根据 OpenAPI 规范指定您 return 的响应类型。像这样：

v1/employees/{employeeId}:
get:
  operationId: getUser
  responses:
    200:
      description: Return user
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UsertResponseDTO'

之后，如果您使用默认模板，请像这样手动添加拼写错误回复：

import javax.ws.rs.core.Response;

@Path("/v1/employees")
public Response getEmployee(String employeeId) {
 
    // ...
 
    return Response.ok(employee).build();
}

Answer 2

为了解决我的问题，我没有返回 Response 对象，而是抛出一个 javax.ws.rs.WebApplicationException 并添加了一个 ExceptionTranslator 代码以将我所有的异常转换为 WebApplicationException。

这里是异常翻译的示例代码。

// Actual code to convert Java exception into javax.ws.rs.WebApplicationException.
catch (Exception e) {
    throw new WebApplicationException(getResponse(e));
}

// Exception translation code sample. This can be made into a nice generic function to handle different types of exceptions.
Response getResponse(Throwable t) {
    if (throwable instanceof NotFoundException) {
        Error error = new Error();
            error.setType("404");
            error.setMessage("Requested entry could not be found");

        Response.status(Status.NOT_FOUND)
            .entity(error)
            .build();
    }
}

如何在 OpenAPI YAML 文件中添加 JAX-RS 响应

How to add JAX-RS Response in OpenAPI YAML file

rest

jax-rs

httpresponse

openapi