{new} @Response

The {@link oaj.http.annotation.Response @Response} annotation is used to identify schema information about an HTTP response.

It can be used in the following locations:

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:

@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 oajr.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).

Example:

@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.

Example:

@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.

Example:

@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:

@RestResource 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.

@RestResource 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"); }

See Also: