How to add JAX-RS Response in OpenAPI YAML file - rest

Question

I have a REST service and I have defined the API signature using OpenAPI's YAML file.
Something like,
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:
....
From the YAML file, I generate the API requests using something like OpenAPI generator.
But how do I specify a https://docs.oracle.com/javaee/7/api/javax/ws/rs/core/Response.html, in my YAML file?
This is how I want to send a response from my Java code. I want to know how I can add this Response object to OpenAPI's YAML?
import javax.ws.rs.core.Response;
#Path("/v1/employees")
public Response getEmployee(String employeeId) {
// ...
return Response
.status(Response.Status.OK)
.entity(employee)
.build();
}
I am new to REST API development. I checked the documentation, but couldn't find details in OpenAPI's on how to add a Javax Response.

Answer 1

Depends on the template you use, by default it is not there, but you can create a custom template to use.
here is the list of available templates.
you must specify type of response you return on OpenAPI spec. like this:
v1/employees/{employeeId}:
get:
operationId: getUser
responses:
200:
description: Return user
content:
application/json:
schema:
$ref: '#/components/schemas/UsertResponseDTO'
after that, if you use default template, add manually typo response like this:
import javax.ws.rs.core.Response;
#Path("/v1/employees")
public Response getEmployee(String employeeId) {
// ...
return Response.ok(employee).build();
}

Answer 2

To solve my problem, instead of returning a Response object, I went with throwing a javax.ws.rs.WebApplicationException and adding an ExceptionTranslator code to convert all my exceptions into a WebApplicationException.
Here is a sample code on the exception translation.
// 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();
}
}