@Response
The {@link oaj.http.annotation.Response @Response} annotation is used to identify schema information about an HTTP response.
- {@link oaj.http.annotation.Response}
- {@link oaj.http.annotation.Response#api() api} - Free-form Swagger JSON.
- {@link oaj.http.annotation.Response#code() code} - HTTP status code.
- {@link oaj.http.annotation.Response#description() description} - Description.
- {@link oaj.http.annotation.Response#example() example} - Serialized example.
- {@link oaj.http.annotation.Response#examples() examples} - Serialized examples per media type.
- {@link oaj.http.annotation.Response#headers() headers} - Swagger about headers added to response.
- {@link oaj.http.annotation.Response#serializer() serializer} - Override the part serializer.
- {@link oaj.http.annotation.Response#schema() schema} - Swagger schema.
- {@link oaj.http.annotation.Response#value() value} - Free-form Swagger JSON.
It can be used in the following locations:
- Exception classes thrown from @RestMethod-annotated methods.
- Return type classes of @RestMethod-annotated methods.
- @RestMethod-annotated methods themselves.
- Arguments and argument-types of @RestMethod-annotated methods.
When the @Response annotation is applied to classes, the following annotations can be used on
public non-static methods of the class to identify parts of a response:
- {@link oaj.http.annotation.ResponseStatus}
- {@link oaj.http.annotation.ResponseHeader}
- {@link oaj.http.annotation.ResponseBody}
@Resource on exception classes
When applied to an exception class, this annotation defines Swagger schema and information on non-200 return types.
The following example shows the @Response annotation used to define an exception for an invalid login attempt:
// Our annotated exception.
@Response(
code=401,
description="Invalid username or password provided" // Description show in Swagger
)
public class InvalidLogin extends Exception {
public InvalidLogin() {
super("Invalid username or password."); // Message sent in response
}
}
// Our REST method that throws an annotated exception.
@RestMethod(name="GET", path="/user/login")
public Ok login(
@FormData("username") String username,
@FormData("password") String password
) throws InvalidLogin
{
checkCredentials(username, password);
return new Ok();
}
Custom exceptions can also extend from one of the predefined HTTP exceptions such as the {@link oaj.http.exception.Unauthorized} exception:
// Our annotated exception.
@Response(
description="Invalid username or password provided" // Overridden from parent class
)
public class InvalidLogin extends Unauthorized {
public InvalidLogin() {
super("Invalid username or password.");
}
}
// Parent predefined exception class.
@Response(
code=401,
description="Unauthorized"
)
public class Unauthorized extends RestException {...}
@Resource on return type classes
When applied type classes returned by a Java method, this annotation defines schema and Swagger information on the body of responses.
In the example above, we're using the Ok class which is defined like so:
@Response(
code=200,
description="OK"
)
public class Ok {
@ResponseBody
public String toString() {
return "OK";
}
}
Another example showing how a redirect can be defined:
@Response(
code=307,
description="Temporary Redirect"
)
public class Redirect {
private final URI location;
public Redirect(URI location) {
this.location = location;
}
@ResponseHeader(
name="Location",
format="uri"
)
public URI getLocation() {
return location;
}
@ResponseBody
public String toString() {
return "Temporary Redirect";
}
}
// Usage
@RestMethod(method=POST)
public Redirect addPet(Pet pet) {
// Redirect to servlet root
return new Redirect(URI.create("servlet:/"));
}
@Resource on @RestMethod-annotated methods
The @Response annotation can also be applied to the Java method itself which is effectively
the same as applying it to the return type (albeit for this method only).
@RestMethod(name="GET", path="/user/login")
@Response(code=200, description="OK")
public Ok login(
@FormData("username") String username,
@FormData("password") String password
) throws InvalidLogin
{
checkCredentials(username, password);
return new Ok();
}
The @Response annotation can be simultaneously on both the Java method and return type.
When used in both locations, the annotation values are combined, but values defined on the
method return annotation take precedence over the values defined on the type.
@Resource on @RestMethod-annotated method parameters
The @Response annotation can also be applied to the Java method parameters when the parameter type
is {@link oaj.Value} (a placeholder for objects).
@RestMethod(name="GET", path="/user/login")
public void login(
@FormData("username") String username,
@FormData("password") String password,
@Response(code=200, description="Login succeeded") Value<String> body
) throws InvalidLogin
{
checkCredentials(username, password);
body.set("OK");
}
@Response-annotated types can also be used as value parameters:
@RestMethod(...)
public void login(
...
@Response Value<Ok> res
) throws InvalidLogin
{
...
res.set(new Ok());
}
In the above example, the @Response annotation is optional since it is inferred from the class
that it's a @Response bean.
@RestMethod(name="GET", path="/user/login")
public void login(
...
Value<Ok> res // @Response annotation not needed.
) throws InvalidLogin
{
...
res.set(new Ok());
}
@ResponseStatus on methods of @Response-annotated types
The {@link oaj.http.annotation.ResponseStatus @ResponseStatus} annotation can be used on
the method of a @Response-annotated class to identify HTTP response
statuses other than 200 (the default).
@Response
public class AddPetSuccess {
@ResponseStatus
public int getStatus() {
return 201;
}
@Override
public String toString() {
return "Pet was successfully added";
}
}
@ResponseHeader on methods of @Response-annotated types
The {@link oaj.http.annotation.ResponseHeader @ResponseHeader} annotation can be used on
the method of a @Response-annotated class to identify a header
to add to the response.
@Response
public class AddPetSuccess {
@ResponseHeader(
name="X-PetId",
type="integer",
format="int32",
description="ID of added pet.",
example="123"
)
public int getPetId() {...}
}
@ResponseBody on methods of @Response-annotated types
The {@link oaj.http.annotation.ResponseBody @ResponseBody} annotation can be used on
the method of a @Response-annotated class to identify a POJO
as the body of the HTTP response.
@Response
public class AddPetSuccess {
@ResponseBody
public Pet getPet() {...}
}
If a @Response class does not have a @ResponseBody-annotated method, then the response
object itself is serialized in the response (typically using toString()).
Notes about OpenAPI part serialization
By default, POJOs representing the body of the request are serialized using the Juneau serializer
matching the requesting Accept header.
The {@link oaj.oapi.OpenApiSerializer} class can be used to serialize response bodies using OpenAPI rules.
The following examples show part-schema-based serialization of response bodies:
@Rest
public class ExampleResource {
// Example 1 - String[] should be serialized using part serializer.
@Response(
serializers=OpenApiSerializer.class,
defaultAccept="text/openapi"
)
@RestMethod
public String[] example1() {
return new String[]{"foo","bar"};
}
// Example 2 - Same as above. Annotation on parameter.
@RestMethod
public void example2(
@Response(
serializers=OpenApiSerializer.class,
defaultAccept="text/openapi"
)
Value<String[]> body
)
{
body.set(new String[]{"foo","bar"});
}
}
The @Response(schema) annotation can be used to define the format of the output using OpenAPI-based rules.
@Rest
public class ExampleResource {
@Response(
serializers=OpenApiSerializer.class,
defaultAccept="text/openapi",
schema=@Schema(collectionFormat="pipes")
)
@RestMethod
public String[] example1() {
return new String[]{"foo","bar"};
}
}
Swagger documentation
The attributes on this annotation are also used to populate the generated Swagger for the method.
For example, in the case of the InvalidLogin example above, the following Swagger is generated:
'/user/login': {
get: {
responses: {
401: {
description: 'Invalid username or password provided'
}
}
}
}
Automatic HTTP status
When the {@link oaj.http.annotation.Response#code() @Response(code)} value is specified,
the HTTP status is automatically set to that value on the response regardless of how it's used.
The following two examples are equivalent:
@RestMethod(name="GET", path="/ok")
public void sendContinue(
@Response(code=100) Value<String> body
)
{
body.set("OK");
}
@RestMethod(name="GET", path="/ok")
public void sendContinue(RestResponse res) {
res.setStatus(100);
res.setOutput("OK");
}
- {@doc RestOpenApiSchemaPartSerializing}