如何在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: [e-mail]
paths:
v1/employees/{employeeId}:
get:
responses:
'200':
content:
....

从YAML文件中，我使用类似OpenAPI生成器的东西生成API请求。

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

这就是我想要从Java代码中发送响应的方式。我想知道如何将这个响应对象添加到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开发的新手。我查看了文档，但在OpenAPI中找不到关于如何添加Javax响应的详细信息。

Answer 1

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

这是可用模板的列表。

您必须指定在OpenAPI规范上返回的响应类型，如下所示：

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

为了解决我的问题，我没有返回响应对象，而是抛出了一个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();
}
}