This is an automated email from the ASF dual-hosted git repository.

jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git


The following commit(s) were added to refs/heads/master by this push:
     new ecb2b6e  Javadocs
ecb2b6e is described below

commit ecb2b6ee31aa41391dc0edb9b41fe01bb98eab62
Author: JamesBognar <jamesbog...@apache.org>
AuthorDate: Sat Aug 11 11:23:15 2018 -0400

    Javadocs
---
 .../org/apache/juneau/http/annotation/Body.java    |   8 +-
 .../apache/juneau/http/annotation/FormData.java    |   8 +-
 .../apache/juneau/http/annotation/HasFormData.java |   2 +-
 .../apache/juneau/http/annotation/HasQuery.java    |   2 +-
 .../org/apache/juneau/http/annotation/Header.java  |   8 +-
 .../org/apache/juneau/http/annotation/Path.java    |   8 +-
 .../org/apache/juneau/http/annotation/Query.java   |   8 +-
 .../org/apache/juneau/http/annotation/Request.java |  11 +-
 .../apache/juneau/http/annotation/Response.java    |   8 +-
 .../juneau/http/annotation/ResponseHeader.java     |  48 +++-
 .../juneau/http/annotation/ResponseStatus.java     |   4 +-
 juneau-doc/src/main/javadoc/overview.html          | 293 ++++++++++++---------
 .../09.HttpPartAnnotations/01.Body.html            |  10 +-
 .../09.HttpPartAnnotations/02.FormData.html        |   1 +
 .../09.HttpPartAnnotations/08.Request.html         |   2 +-
 .../09.HttpPartAnnotations/09.Response.html        | 236 ++++++++++-------
 .../09.HttpPartAnnotations/10.ResponseHeader.html  |  23 +-
 .../09.HttpPartAnnotations/11.ResponseStatus.html  |  17 +-
 18 files changed, 405 insertions(+), 292 deletions(-)

diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Body.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Body.java
index 6f64083..a63cfd1 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Body.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Body.java
@@ -34,11 +34,11 @@ import org.apache.juneau.serializer.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * <p>
  * On server-side REST, this annotation can be applied to method parameters or 
parameter classes to identify them as the body of an HTTP request.
@@ -106,7 +106,7 @@ import org.apache.juneau.serializer.*;
  *     <li class='link'><a class="doclink" 
href="https://swagger.io/specification/v2/#parameterObject";>Swagger 
Specification &gt; Parameter Object</a>
  * </ul>
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable-annotated interfaces</h5>
  *
  * Annotation applied to Java method arguments of interface proxies to denote 
that they are the HTTP body of the request.
  *
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/FormData.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/FormData.java
index c441fa2..cd875e4 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/FormData.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/FormData.java
@@ -33,11 +33,11 @@ import org.apache.juneau.jsonschema.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * Annotation that can be applied to a parameter of a 
<ja>@RestMethod</ja>-annotated method to identify it as a form-data parameter.
  *
@@ -80,7 +80,7 @@ import org.apache.juneau.jsonschema.*;
  * The {@link Query @Query} annotation can be used to retrieve a URL parameter 
in the URL string without triggering the
  * servlet to drain the body content.
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable├č-annotated interfaces</h5>
  * Annotation applied to Java method arguments of interface proxies to denote 
that they are FORM post parameters on the
  * request.
  *
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasFormData.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasFormData.java
index ac7f5aa..8e90ce0 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasFormData.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasFormData.java
@@ -25,7 +25,7 @@ import java.lang.annotation.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
  * </ul>
  *
  * <h5 class='section'>See Also:</h5>
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasQuery.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasQuery.java
index 491b583..16cebce 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasQuery.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/HasQuery.java
@@ -26,7 +26,7 @@ import java.lang.annotation.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
  * </ul>
  *
  * <h5 class='section'>See Also:</h5>
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Header.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Header.java
index 46564c0..46fa2f6 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Header.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Header.java
@@ -32,11 +32,11 @@ import org.apache.juneau.jsonschema.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * Annotation that can be applied to a parameter of a 
<ja>@RestMethod</ja>-annotated method to identify it as a HTTP
  * request header.
@@ -64,7 +64,7 @@ import org.apache.juneau.jsonschema.*;
  *     <li class='link'><a class="doclink" 
href="https://swagger.io/specification/v2/#parameterObject";>Swagger 
Specification &gt; Parameter Object</a>
  * </ul>
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable-annotated interfaces</h5>
  *
  * Annotation applied to Java method arguments of interface proxies to denote 
that they are serialized as an HTTP
  * header value.
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Path.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Path.java
index 90ab856..e66e310 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Path.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Path.java
@@ -31,11 +31,11 @@ import org.apache.juneau.jsonschema.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * Annotation that can be applied to a parameter of a 
<ja>@RestMethod</ja>-annotated method to identify it as a variable
  * in a URL path pattern.
@@ -61,7 +61,7 @@ import org.apache.juneau.jsonschema.*;
  *     <li class='link'><a class="doclink" 
href="https://swagger.io/specification/v2/#parameterObject";>Swagger 
Specification &gt; Parameter Object</a>
  * </ul>
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable-annotated interfaces</h5>
  *
  * Annotation applied to Java method arguments of interface proxies to denote 
that they are path variables on the request.
  *
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Query.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Query.java
index befffb0..51f95bf 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Query.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Query.java
@@ -33,11 +33,11 @@ import org.apache.juneau.jsonschema.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * Annotation that can be applied to a parameter of a 
<ja>@RestMethod</ja>-annotated method to identify it as a URL query parameter.
  *
@@ -76,7 +76,7 @@ import org.apache.juneau.jsonschema.*;
  *     <li class='link'><a class="doclink" 
href="https://swagger.io/specification/v2/#parameterObject";>Swagger 
Specification &gt; Parameter Object</a>
  * </ul>
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable-annotated interfaces</h5>
  *
  * Annotation applied to Java method arguments of interface proxies to denote 
that they are QUERY parameters on the
  * request.
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Request.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Request.java
index 53205fc..8c24209 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Request.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Request.java
@@ -28,11 +28,11 @@ import org.apache.juneau.httppart.*;
  * <p>
  * Can be used in the following locations:
  * <ul>
- *     <li>Java method arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated REST interface proxies.
- *     <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of client-side 
<ja>@Remoteable</ja>-annotated interfaces.
  * </ul>
  *
- * <h5 class='topic'>Server-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of server-side 
@RestMethod-annotated methods</h5>
  *
  * Annotation that can be applied to a parameter of a 
<ja>@RestMethod</ja>-annotated method to identify it as an interface for 
retrieving HTTP parts through a bean interface.
  *
@@ -82,15 +82,12 @@ import org.apache.juneau.httppart.*;
  * The return types of the getters must be the supported parameter types for 
the HTTP-part annotation used.
  * <br>Schema-based serialization and parsing is allowed just as if used as 
individual parameter types.
  *
- * <p>
- * TODO - Swagger-info in <ja>@Request</ja>s is not currently reflected in 
generated Swagger documentation.
- *
  * <h5 class='section'>See Also:</h5>
  * <ul>
  *     <li class='link'><a class="doclink" 
href="../../../../../overview-summary.html#juneau-rest-server.HttpPartAnnotations.Request">Overview
 &gt; juneau-rest-server &gt; @Request</a>
  * </ul>
  *
- * <h5 class='topic'>Client-side REST</h5>
+ * <h5 class='topic'>Arguments and argument-types of client-side 
@Remoteable-annotated interfaces</h5>
  *
  * Annotation applied to Java method arguments of interface proxies to denote 
a bean with remoteable annotations.
 
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Response.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Response.java
index 0c16949..0503a67 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Response.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Response.java
@@ -31,10 +31,10 @@ import org.apache.juneau.jsonschema.*;
  * <p>
  * Can be used in the following locations:
  *  <ul>
- *     <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST 
Java methods.
- *     <li>Return type classes of <ja>@RestMethod</ja>-annotated REST Java 
methods.
- *     <li><ja>@RestMethod</ja>-annotated REST Java methods themselves.
- *     <li>Java method arguments and argument-types of 
<ja>@RestMethod</ja>-annotated REST Java methods.
+ *     <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated 
methods.
+ *     <li>Return type classes of <ja>@RestMethod</ja>-annotated methods.
+ *     <li><ja>@RestMethod</ja>-annotated methods.
+ *     <li>Arguments and argument-types of <ja>@RestMethod</ja>-annotated 
methods.
  * </ul>
  *
  * <p>
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseHeader.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseHeader.java
index 38f4927..97f2092 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseHeader.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseHeader.java
@@ -30,12 +30,14 @@ import org.apache.juneau.httppart.*;
  * Can be used in the following locations:
  * <ul>
  *     <li>Arguments of server-side <ja>@RestMethod</ja>-annotated methods.
- *     <li>Argument types of server-side <ja>@RestMethod</ja>-annotated 
methods.
- *     <li>Public methods of <ja>@Response</ja>-annotated methods.
+ *     <li>Public methods of <ja>@Response</ja>-annotated types.
  * </ul>
  *
+ * <h5 class='topic'>Arguments of server-side <ja>@RestMethod</ja>-annotated 
methods</h5>
+ *
  * <p>
- * This annotation can only be applied to subclasses of type {@link Value}.
+ * On server-side REST, this annotation can be applied to method parameters to 
identify them as an HTTP response header.
+ * <br>In this case, the annotation can only be applied to subclasses of type 
{@link Value}.
  *
  * <p>
  * The following examples show 3 different ways of accomplishing the same task 
of setting an HTTP header
@@ -67,15 +69,47 @@ import org.apache.juneau.httppart.*;
  *
  *     <jc>// Example #3 - Use on type.</jc>
  *     <ja>@RestMethod</ja>(...)
- *     <jk>public void</jk> login(RateLimit rateLimit) {
- *             rateLimit.set(1000);
+ *     <jk>public void</jk> login(Value&lt;RateLimit&gt; rateLimit) {
+ *             rateLimit.set(new RateLimit(1000));
  *             ...
  *     }
  *
- *     <ja>@ResponseHeader</ja>(name=<js>"X-Rate-Limit"</js>, 
type=<js>"integer"</js>, format=<js>"int32"</js>, description=<js>"Calls per 
hour allowed by the user."</js>, example=<js>"123"</js>)
- *     <jk>public static class</jk> RateLimit <jk>extends</jk> 
Value&lt;Integer&gt; {}
+ *     <ja>@ResponseHeader</ja>(
+ *             name=<js>"X-Rate-Limit"</js>,
+ *             type=<js>"integer"</js>,
+ *             format=<js>"int32"</js>,
+ *             description=<js>"Calls per hour allowed by the user."</js>,
+ *             example=<js>"123"</js>
+ *     )
+ *     <jk>public class</jk> RateLimit {
+ *             <jc>// OpenApiPartSerializer knows to look for this method 
based on format/type.</jc>
+ *             <jk>public</jk> Integer toInteger() {
+ *                     <jk>return</jk> 1000;
+ *             }
+ *     }
  * </p>
  *
+ * <h5 class='topic'>Public methods of @Response-annotated types</h5>
+ *
+ * <p>
+ * On server-side REST, this annotation can also be applied to public methods 
of {@link Response}-annotated methods.
+ *
+ * <p class='bcode w800'>
+ *     <ja>@Response</ja>
+ *     <jk>public class</jk> AddPetSuccess {
+ *
+ *             <ja>@ResponseHeader</ja>(
+ *                     name=<js>"X-PetId"</js>,
+ *                     type=<js>"integer"</js>,
+ *                     format=<js>"int32"</js>,
+ *                     description=<js>"ID of added pet."</js>,
+ *                     example=<js>"123"</js>
+ *             )
+ *             <jk>public int</jk> getPetId() {...}
+ *     }
+ * </p>
+ *
+ *
  * <h5 class='section'>See Also:</h5>
  * <ul>
  *     <li class='link'><a class="doclink" 
href="../../../../../overview-summary.html#juneau-rest-server.HttpPartAnnotations.ResponseHeader">Overview
 &gt; juneau-rest-server &gt; @ResponseHeader</a>
diff --git 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatus.java
 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatus.java
index 2299acd..460ea4b 100644
--- 
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatus.java
+++ 
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatus.java
@@ -29,7 +29,7 @@ import org.apache.juneau.*;
  * Can be used in the following locations:
  * <ul>
  *     <li>Arguments of server-side <ja>@RestMethod</ja>-annotated methods.
- *     <li>Public methods of <ja>@Response</ja>-annotated methods.
+ *     <li>Public methods of <ja>@Response</ja>-annotated types.
  * </ul>
  *
  * <h5 class='topic'>Arguments of server-side <ja>@RestMethod</ja>-annotated 
methods</h5>
@@ -49,7 +49,7 @@ import org.apache.juneau.*;
  * <p>
  * The parameter type must be {@link Value} with a parameterized type of 
{@link Integer}.
  *
- * <h5 class='topic'>Public methods of <ja>@Response</ja>-annotated 
methods</h5>
+ * <h5 class='topic'>Public methods of <ja>@Response</ja>-annotated types</h5>
  *
  *
  * <p>
diff --git a/juneau-doc/src/main/javadoc/overview.html 
b/juneau-doc/src/main/javadoc/overview.html
index 4e0f8a9..4fdb959 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -313,9 +313,9 @@
                        <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.Header'>@Header</a></p>
                        <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.Path'>@Path</a></p>
                        <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.Request'>@Request</a></p>
-                       <li><p class='todo'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.Response'>@Response</a></p>
-                       <li><p class='todo'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.ResponseHeader'>@ResponseHeader</a></p>
-                       <li><p class='todo'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.ResponseStatus'>@ResponseStatus</a></p>
+                       <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.Response'>@Response</a></p>
+                       <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.ResponseHeader'>@ResponseHeader</a></p>
+                       <li><p class='new'><a class='doclink' 
href='#juneau-rest-server.HttpPartAnnotations.ResponseStatus'>@ResponseStatus</a></p>
                </ol>
                <li><p class=''><a class='doclink' 
href='#juneau-rest-server.HandlingFormPosts'>Handling Form Posts</a></p>
                <li><p class=''><a class='doclink' 
href='#juneau-rest-server.HandlingMultiPartFormPosts'>Handling Multi-Part Form 
Posts</a></p>
@@ -14650,15 +14650,7 @@ TODO(7.2.0)
                <li class='jf'>{@link 
org.apache.juneau.http.annotation.Body#value() value()} - Free-form Swagger 
JSON.
        </ul>
 </ul>
-<p>
-       This annotation can be applied at the following locations:
-</p>
-<ul class='spaced-list'>
-       <li>
-               Parameters on a <ja>@RestMethod</ja>-annotated method.
-       <li>
-               POJO classes used as parameters on a 
<ja>@RestMethod</ja>-annotated method.
-</ul>
+
 <h5 class='figure'>Examples:</h5>
 <p class='bpcode w800'>
        <jc>// Defined on parameter</jc>
@@ -14858,6 +14850,7 @@ TODO(7.2.0)
                <li class='jf'>{@link 
org.apache.juneau.http.annotation.FormData#value() value()} - Free-form Swagger 
JSON.
        </ul>
 </ul>
+
 <p>
        The most typical scenario is to simply use the <code>value</code> field 
to define form data parameter names:
 </p>
@@ -15699,7 +15692,7 @@ TODO(7.2.0)
                                maximumLength=10
                        )
                )
-               <jk>int</jk>[][] getPipeCdlInts();
+               <jk>int</jk>[][] getPipedCdlInts();
        }
 </p>
 <p>
@@ -15717,7 +15710,7 @@ TODO(7.2.0)
 
 <!-- 
====================================================================================================
 -->
 
-<h4 class='topic todo' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.Response' 
id='juneau-rest-server.HttpPartAnnotations.Response'>7.9.9 - @Response</a></h4>
+<h4 class='topic new' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.Response' 
id='juneau-rest-server.HttpPartAnnotations.Response'>7.9.9 - @Response</a></h4>
 <div class='topic'><!-- START: 7.9.9 - 
juneau-rest-server.HttpPartAnnotations.Response -->
 <p>
        The {@link org.apache.juneau.http.annotation.Response @Response} 
annotation is used to identify schema information about an HTTP response.
@@ -15741,10 +15734,10 @@ TODO(7.2.0)
        It can be used in the following locations:
 </p>
 <ul>
-       <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST 
Java methods.
-       <li>Return type classes of <ja>@RestMethod</ja>-annotated REST Java 
methods.
-       <li><ja>@RestMethod</ja>-annotated REST Java methods themselves.
-       <li>Java method arguments and argument-types of 
<ja>@RestMethod</ja>-annotated REST Java methods.
+       <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated 
methods.
+       <li>Return type classes of <ja>@RestMethod</ja>-annotated methods.
+       <li><ja>@RestMethod</ja>-annotated methods themselves.
+       <li>Arguments and argument-types of <ja>@RestMethod</ja>-annotated 
methods.
 </ul>
 
 <p>
@@ -15801,7 +15794,7 @@ TODO(7.2.0)
                }
        }
 
-       <jc>// Parent exception class.</jc>
+       <jc>// Parent predefined exception class.</jc>
        <ja>@Response</ja>(
                code=401, 
                description=<js>"Unauthorized"</js>
@@ -15817,35 +15810,64 @@ TODO(7.2.0)
        In the example above, we're using the <code>Ok</code> class which is 
defined like so:
 </p>
 <p class='bpcode w800'>
-       <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
-       <jk>public class</jk> Ok {...}
+       <ja>@Response</ja>(
+               code=200, 
+               description=<js>"OK"</js>
+       )
+       <jk>public class</jk> Ok {
+
+               <ja>@ResponseBody</ja>
+               <jk>public</jk> String toString() {
+                       <jk>return</jk> <js>"OK"</js>;
+               }
+       }
 </p>
 <p>
-       Another example is <code>Redirect</code> which is defined like so:
+       Another example showing how a redirect can be defined:
 </p>
 <p class='bpcode w800'>
        <ja>@Response</ja>(
-               code=302,
-               description=<js>"Redirect"</js>,
-               headers={ <jc>// Added to Swagger documentation</jc>
-                       <ja>@ResponseHeader</ja>(
-                               name=<js>"Location"</js>,
-                               type=<js>"string"</js>,
-                               format=<js>"uri"</js>
-                       )
-               }
+               code=307,
+               description=<js>"Temporary Redirect"</js>
        )
-       <jk>public class</jk> Redirect {...}
+       <jk>public class</jk> Redirect {
+               <jk>private final</jk> URI <jf>location</jf>;
+       
+               <jk>public</jk> Redirect(URI location) {
+                       <jk>this</jk>.<jf>location</jf> = location;
+               }
+       
+               <ja>@ResponseHeader</ja>(
+                       name=<js>"Location"</js>,
+                       format=<js>"uri"</js>
+               )
+               <jk>public</jk> URI getLocation() {
+                       <jk>return</jk> location;
+               }
+
+               <ja>@ResponseBody</ja>
+               <jk>public</jk> String toString() {
+                       <jk>return</jk> <js>"Temporary Redirect"</js>;
+               }
+       }
+</p>
+<p class='bpcode w800'>
+       <jc>// Usage</jc>
+       <ja>@RestMethod</ja>(method=<jsf>POST</jsf>)
+       <jk>public</jk> Redirect addPet(Pet pet) {
+               <jc>// Redirect to servlet root</jc>
+               <jk>return new</jk> 
Redirect(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
+       }
 </p>
 
-<h5 class='topic'>@Resource on @RestMethod-annotated method</h5>
+<h5 class='topic'>@Resource on @RestMethod-annotated methods</h5>
 <p>
        The <ja>@Response</ja> 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).
 </p>
 <p class='bpcode w800'>
        <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
-       <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
+       <ja>@Response</ja>(code=200, description=<js>"OK"</js>)
        <jk>public</jk> Ok login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password
@@ -15861,7 +15883,7 @@ TODO(7.2.0)
        method return annotation take precedence over the values defined on the 
type.
 </p>
 
-<h5 class='topic'>@Resource on @RestMethod-annotated method parameter</h5>
+<h5 class='topic'>@Resource on @RestMethod-annotated method parameters</h5>
 <p>
        The <ja>@Response</ja> annotation can also be applied to the Java 
method parameters when the parameter type 
        is {@link org.apache.juneau.Value} (a placeholder for objects).
@@ -15871,86 +15893,47 @@ TODO(7.2.0)
        <jk>public void</jk> login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password,
-               <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>) 
Value&lt;String&gt; body
+               <ja>@Response</ja>(code=200, description=<js>"Login 
succeeded"</js>) Value&lt;String&gt; body
        ) <jk>throws</jk> InvalidLogin 
        {
                checkCredentials(username, password);
                body.set(<js>"OK"</js>);
        }
 </p>
-
-<h5 class='topic'>OpenAPI part serialization</h5>
 <p>
-       By default, POJOs representing the body of the request are serialized 
using the Juneau serializer
-       matching the requesting <code>Accept</code> header.
-       <br>It is also possible to use OpenAPI part serialization for the body 
of the response using 
-       the {@link 
org.apache.juneau.http.annotation.Response#usePartSerializer() 
usePartSerializer} flag.
-       <br>The flag is needed to identify that we should use the part 
serializer instead of normal serializers for the POJO.
-</p>
-<p>
-       The following examples show part-schema-based serialization of response 
bodies:
+       <ja>@Response</ja>-annotated types can also be used as value parameters:
 </p>
 <p class='bpcode w800'>
-       <ja>@RestResource</ja>
-       <jk>public class</jk> ExampleResource {
-
-               <jc>// Example 1 - String[] should be serialized using part 
serializer.</jc>
-               <ja>@Response</ja>(
-                       usePartSerializer=<jk>true</jk>
-               )
-               <ja>@RestMethod</ja>
-               <jk>public</jk> String[] example1() {
-                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
-               }
-
-               <jc>// Example 2 - Same as above.  Annotation on parameter.</jc>
-               <ja>@RestMethod</ja>
-               <jk>public void</jk> example2(
-                       <ja>@Response</ja>(
-                               usePartSerializer=<jk>true</jk>
-                       ) 
-                       Value&lt;String[]&gt; body
-               ) 
-               {
-                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
-               }
+       <ja>@RestMethod</ja>(...)
+       <jk>public void</jk> login(
+               ...
+               <ja>@Response</ja> Value&lt;Ok&gt; res
+       ) <jk>throws</jk> InvalidLogin 
+       {
+               ...
+               res.set(<jk>new</jk> Ok());
        }
 </p>
 <p>
-       The <code>usePartSerializer</code> flag is assumed to be <jk>true</jk> 
if you specify <code>schema</code>
-       or <code>partSerializer</code> on the annotation.
+       In the above example, the <ja>@Response</ja> annotation is optional 
since it is inferred from the class
+       that it's a <ja>@Response</ja> bean.
 </p>
 <p class='bpcode w800'>
-       <ja>@RestResource</ja>
-       <jk>public class</jk> ExampleResource {
-
-               <jc>// Example 1 - Part serializer used because schema is 
defined</jc>
-               <ja>@Response</ja>(
-                       
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
-               )
-               <ja>@RestMethod</ja>
-               <jk>public</jk> String[] example1() {
-                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
-               }
-
-               <jc>// Example 2 - Part serializer used because partSerializer 
is defined</jc>
-               <ja>@RestMethod</ja>
-               <jk>public void</jk> example2(
-                       <ja>@Response</ja>(
-                               
partSerializer=OpenApiPartSerializer.<jk>class</jk>
-                       ) 
-                       Value&lt;String[]&gt; body
-               ) 
-               {
-                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
-               }
+       <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+       <jk>public void</jk> login(
+               ...
+               Value&lt;Ok&gt; res  <jc>// @Response annotation not 
needed.</jc>
+       ) <jk>throws</jk> InvalidLogin 
+       {
+               ...
+               res.set(<jk>new</jk> Ok());
        }
 </p>
 
-<h5 class='topic'>@ResponseStatus</h5>
+<h5 class='topic'>@ResponseStatus on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation can be used on 
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify HTTP 
response
+       the method of a <ja>@Response</ja>-annotated class to identify HTTP 
response
        statuses other than <code>200</code> (the default).     
 </p>
 
@@ -15972,15 +15955,15 @@ TODO(7.2.0)
 </p>
 
 
-<h5 class='topic'>@ResponseHeader</h5>
+<h5 class='topic'>@ResponseHeader on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation can be used on
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify a header
+       the method of a <ja>@Response</ja>-annotated class to identify a header
        to add to the response.
 </p>
 
 <h5 class='figure'>Example:</h5>
-<p class='bcode w800'>
+<p class='bpcode w800'>
        <ja>@Response</ja>
        <jk>public class</jk> AddPetSuccess {
  
@@ -15995,15 +15978,15 @@ TODO(7.2.0)
        }
 </p>
 
-<h5 class='topic'>@ResponseBody</h5>
+<h5 class='topic'>@ResponseBody on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseBody 
@ResponseBody} annotation can be used on
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify a POJO
+       the method of a <ja>@Response</ja>-annotated class to identify a POJO
        as the body of the HTTP response.
 </p>
 
 <h5 class='figure'>Example:</h5>
-<p class='bcode w800'>
+<p class='bpcode w800'>
        <ja>@Response</ja>
        <jk>public class</jk> AddPetSuccess {
  
@@ -16017,6 +16000,74 @@ TODO(7.2.0)
        object itself is serialized in the response (typically using 
<code>toString()</code>).
 </p>
 
+<h5 class='topic'>Notes about OpenAPI part serialization</h5>
+<p>
+       By default, POJOs representing the body of the request are serialized 
using the Juneau serializer
+       matching the requesting <code>Accept</code> header.
+       <br>It is also possible to use OpenAPI part serialization for the body 
of the response using 
+       the {@link 
org.apache.juneau.http.annotation.Response#usePartSerializer() 
usePartSerializer} flag.
+       <br>The flag is needed to identify that we should use the part 
serializer instead of normal serializers for the POJO.
+</p>
+<p>
+       The following examples show part-schema-based serialization of response 
bodies:
+</p>
+<p class='bpcode w800'>
+       <ja>@RestResource</ja>
+       <jk>public class</jk> ExampleResource {
+
+               <jc>// Example 1 - String[] should be serialized using part 
serializer.</jc>
+               <ja>@Response</ja>(
+                       usePartSerializer=<jk>true</jk>
+               )
+               <ja>@RestMethod</ja>
+               <jk>public</jk> String[] example1() {
+                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
+               }
+
+               <jc>// Example 2 - Same as above.  Annotation on parameter.</jc>
+               <ja>@RestMethod</ja>
+               <jk>public void</jk> example2(
+                       <ja>@Response</ja>(
+                               usePartSerializer=<jk>true</jk>
+                       ) 
+                       Value&lt;String[]&gt; body
+               ) 
+               {
+                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
+               }
+       }
+</p>
+<p>
+       The <code>usePartSerializer</code> flag is assumed to be <jk>true</jk> 
if you specify <code>schema</code>
+       or <code>partSerializer</code> on the annotation.
+</p>
+<p class='bpcode w800'>
+       <ja>@RestResource</ja>
+       <jk>public class</jk> ExampleResource {
+
+               <jc>// Example 1 - Part serializer used because schema is 
defined</jc>
+               <ja>@Response</ja>(
+                       
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+               )
+               <ja>@RestMethod</ja>
+               <jk>public</jk> String[] example1() {
+                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
+               }
+
+               <jc>// Example 2 - Part serializer used because partSerializer 
is defined</jc>
+               <ja>@RestMethod</ja>
+               <jk>public void</jk> example2(
+                       <ja>@Response</ja>(
+                               
partSerializer=OpenApiPartSerializer.<jk>class</jk>
+                       ) 
+                       Value&lt;String[]&gt; body
+               ) 
+               {
+                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
+               }
+       }
+</p>
+
 <h5 class='topic'>Swagger documentation</h5>
 <p>
        The attributes on this annotation are also used to populate the 
generated Swagger for the method.
@@ -16067,10 +16118,10 @@ TODO(7.2.0)
 
 <!-- 
====================================================================================================
 -->
 
-<h4 class='topic todo' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.ResponseHeader' 
id='juneau-rest-server.HttpPartAnnotations.ResponseHeader'>7.9.10 - 
@ResponseHeader</a></h4>
+<h4 class='topic new' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.ResponseHeader' 
id='juneau-rest-server.HttpPartAnnotations.ResponseHeader'>7.9.10 - 
@ResponseHeader</a></h4>
 <div class='topic'><!-- START: 7.9.10 - 
juneau-rest-server.HttpPartAnnotations.ResponseHeader -->
 <p>
-       The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation is applied to parameters and parameter types to 
denote them as an HTTP response headers.
+       The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation can be applied to <ja>@RestMethod</ja>-annotated 
parameters to denote them as an HTTP response headers.
 </p>
 <ul class='doctree'>
        <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader 
ResponseHeader}
@@ -16103,13 +16154,7 @@ TODO(7.2.0)
        </ul>
 </ul>
 <p>
-       It can be used in the following locations:
-</p>
-<ul>
-       <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
-</ul>
-<p>
-       This annotation can only be applied to subclasses or parameters of type 
{@link org.apache.juneau.Value}.
+       This annotation can only be applied to parameters of type {@link 
org.apache.juneau.Value}.
 </p>
 <p>
        The following examples show 3 different ways of accomplishing the same 
task of setting an HTTP header
@@ -16142,8 +16187,8 @@ TODO(7.2.0)
 
        <jc>// Example #3 - Use on type.</jc>
        <ja>@RestMethod</ja>(...)
-       <jk>public void</jk> login(RateLimit rateLimit) {
-               rateLimit.set(1000);
+       <jk>public void</jk> login(Value&lt;RateLimit&gt; rateLimit) {
+               rateLimit.set(<jk>new</jk> RateLimit());
                ...
        }
 
@@ -16154,7 +16199,12 @@ TODO(7.2.0)
                description=<js>"Calls per hour allowed by the user."</js>, 
                example=<js>"123"</js>
        )
-       <jk>public class</jk> RateLimit <jk>extends</jk> Value&lt;Integer&gt; {}
+       <jk>public class</jk> RateLimit {
+               <jc>// OpenApiPartSerializer knows to look for this method 
based on format/type.</jc>
+               <jk>public</jk> Integer toInteger() {
+                       <jk>return</jk> 1000;
+               }
+       }
 </p>
 
 <h5 class='topic'>Swagger documentation</h5>
@@ -16184,24 +16234,16 @@ TODO(7.2.0)
 
 <!-- 
====================================================================================================
 -->
 
-<h4 class='topic todo' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.ResponseStatus' 
id='juneau-rest-server.HttpPartAnnotations.ResponseStatus'>7.9.11 - 
@ResponseStatus</a></h4>
+<h4 class='topic new' onclick='toggle(this)'><a 
href='#juneau-rest-server.HttpPartAnnotations.ResponseStatus' 
id='juneau-rest-server.HttpPartAnnotations.ResponseStatus'>7.9.11 - 
@ResponseStatus</a></h4>
 <div class='topic'><!-- START: 7.9.11 - 
juneau-rest-server.HttpPartAnnotations.ResponseStatus -->
 <p>
-       The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation is applied to parameters and parameter 
-       types to denote them as an HTTP response status on server-side REST 
method parameters.
+       The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation annotation can be applied to 
<ja>@RestMethod</ja>-annotated parameters to denote them as an HTTP response 
status codes.
 </p>
 <ul class='doctree'>
        <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseStatus 
ResponseStatus}
 </ul>
 <p>
-       It can be used in the following locations:
-</p>
-<ul>
-       <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
-</ul>
-<p>
        This can only be applied to parameters of the {@link 
org.apache.juneau.Value} class with an {@link java.lang.Integer} type.
-       <br>The {@link org.apache.juneau.Value} object is mean to be a 
place-holder for the set value.
 </p>
 
 <h5 class='section'>Examples:</h5>
@@ -16211,8 +16253,7 @@ TODO(7.2.0)
        <jk>public void</jk> login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password,
-               <ja>@ResponseStatus</ja> 
-               Value&lt;Integer&gt; status
+               <ja>@ResponseStatus</ja> Value&lt;Integer&gt; status
        ) 
        {
                <jk>if</jk> (! isValid(username, password))
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/01.Body.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/01.Body.html
index e36b3f6..f6eea0e 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/01.Body.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/01.Body.html
@@ -32,15 +32,7 @@
                <li class='jf'>{@link 
org.apache.juneau.http.annotation.Body#value() value()} - Free-form Swagger 
JSON.
        </ul>
 </ul>
-<p>
-       This annotation can be applied at the following locations:
-</p>
-<ul class='spaced-list'>
-       <li>
-               Parameters on a <ja>@RestMethod</ja>-annotated method.
-       <li>
-               POJO classes used as parameters on a 
<ja>@RestMethod</ja>-annotated method.
-</ul>
+
 <h5 class='figure'>Examples:</h5>
 <p class='bpcode w800'>
        <jc>// Defined on parameter</jc>
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/02.FormData.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/02.FormData.html
index 559ef76..6a09e27 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/02.FormData.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/02.FormData.html
@@ -48,6 +48,7 @@
                <li class='jf'>{@link 
org.apache.juneau.http.annotation.FormData#value() value()} - Free-form Swagger 
JSON.
        </ul>
 </ul>
+
 <p>
        The most typical scenario is to simply use the <code>value</code> field 
to define form data parameter names:
 </p>
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/08.Request.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/08.Request.html
index 9505b4c..6f6868a 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/08.Request.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/08.Request.html
@@ -78,7 +78,7 @@
                                maximumLength=10
                        )
                )
-               <jk>int</jk>[][] getPipeCdlInts();
+               <jk>int</jk>[][] getPipedCdlInts();
        }
 </p>
 <p>
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/09.Response.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/09.Response.html
index ca8d98c..18e8fbe 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/09.Response.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/09.Response.html
@@ -13,7 +13,7 @@
  
***************************************************************************************************************************/
  -->
 
-{todo} @Response
+{new} @Response
 
 <p>
        The {@link org.apache.juneau.http.annotation.Response @Response} 
annotation is used to identify schema information about an HTTP response.
@@ -37,10 +37,10 @@
        It can be used in the following locations:
 </p>
 <ul>
-       <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST 
Java methods.
-       <li>Return type classes of <ja>@RestMethod</ja>-annotated REST Java 
methods.
-       <li><ja>@RestMethod</ja>-annotated REST Java methods themselves.
-       <li>Java method arguments and argument-types of 
<ja>@RestMethod</ja>-annotated REST Java methods.
+       <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated 
methods.
+       <li>Return type classes of <ja>@RestMethod</ja>-annotated methods.
+       <li><ja>@RestMethod</ja>-annotated methods themselves.
+       <li>Arguments and argument-types of <ja>@RestMethod</ja>-annotated 
methods.
 </ul>
 
 <p>
@@ -97,7 +97,7 @@
                }
        }
 
-       <jc>// Parent exception class.</jc>
+       <jc>// Parent predefined exception class.</jc>
        <ja>@Response</ja>(
                code=401, 
                description=<js>"Unauthorized"</js>
@@ -113,35 +113,64 @@
        In the example above, we're using the <code>Ok</code> class which is 
defined like so:
 </p>
 <p class='bpcode w800'>
-       <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
-       <jk>public class</jk> Ok {...}
+       <ja>@Response</ja>(
+               code=200, 
+               description=<js>"OK"</js>
+       )
+       <jk>public class</jk> Ok {
+
+               <ja>@ResponseBody</ja>
+               <jk>public</jk> String toString() {
+                       <jk>return</jk> <js>"OK"</js>;
+               }
+       }
 </p>
 <p>
-       Another example is <code>Redirect</code> which is defined like so:
+       Another example showing how a redirect can be defined:
 </p>
 <p class='bpcode w800'>
        <ja>@Response</ja>(
-               code=302,
-               description=<js>"Redirect"</js>,
-               headers={ <jc>// Added to Swagger documentation</jc>
-                       <ja>@ResponseHeader</ja>(
-                               name=<js>"Location"</js>,
-                               type=<js>"string"</js>,
-                               format=<js>"uri"</js>
-                       )
-               }
+               code=307,
+               description=<js>"Temporary Redirect"</js>
        )
-       <jk>public class</jk> Redirect {...}
+       <jk>public class</jk> Redirect {
+               <jk>private final</jk> URI <jf>location</jf>;
+       
+               <jk>public</jk> Redirect(URI location) {
+                       <jk>this</jk>.<jf>location</jf> = location;
+               }
+       
+               <ja>@ResponseHeader</ja>(
+                       name=<js>"Location"</js>,
+                       format=<js>"uri"</js>
+               )
+               <jk>public</jk> URI getLocation() {
+                       <jk>return</jk> location;
+               }
+
+               <ja>@ResponseBody</ja>
+               <jk>public</jk> String toString() {
+                       <jk>return</jk> <js>"Temporary Redirect"</js>;
+               }
+       }
+</p>
+<p class='bpcode w800'>
+       <jc>// Usage</jc>
+       <ja>@RestMethod</ja>(method=<jsf>POST</jsf>)
+       <jk>public</jk> Redirect addPet(Pet pet) {
+               <jc>// Redirect to servlet root</jc>
+               <jk>return new</jk> 
Redirect(URI.<jsm>create</jsm>(<js>"servlet:/"</js>));
+       }
 </p>
 
-<h5 class='topic'>@Resource on @RestMethod-annotated method</h5>
+<h5 class='topic'>@Resource on @RestMethod-annotated methods</h5>
 <p>
        The <ja>@Response</ja> 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).
 </p>
 <p class='bpcode w800'>
        <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
-       <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
+       <ja>@Response</ja>(code=200, description=<js>"OK"</js>)
        <jk>public</jk> Ok login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password
@@ -157,7 +186,7 @@
        method return annotation take precedence over the values defined on the 
type.
 </p>
 
-<h5 class='topic'>@Resource on @RestMethod-annotated method parameter</h5>
+<h5 class='topic'>@Resource on @RestMethod-annotated method parameters</h5>
 <p>
        The <ja>@Response</ja> annotation can also be applied to the Java 
method parameters when the parameter type 
        is {@link org.apache.juneau.Value} (a placeholder for objects).
@@ -167,86 +196,47 @@
        <jk>public void</jk> login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password,
-               <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>) 
Value&lt;String&gt; body
+               <ja>@Response</ja>(code=200, description=<js>"Login 
succeeded"</js>) Value&lt;String&gt; body
        ) <jk>throws</jk> InvalidLogin 
        {
                checkCredentials(username, password);
                body.set(<js>"OK"</js>);
        }
 </p>
-
-<h5 class='topic'>OpenAPI part serialization</h5>
 <p>
-       By default, POJOs representing the body of the request are serialized 
using the Juneau serializer
-       matching the requesting <code>Accept</code> header.
-       <br>It is also possible to use OpenAPI part serialization for the body 
of the response using 
-       the {@link 
org.apache.juneau.http.annotation.Response#usePartSerializer() 
usePartSerializer} flag.
-       <br>The flag is needed to identify that we should use the part 
serializer instead of normal serializers for the POJO.
-</p>
-<p>
-       The following examples show part-schema-based serialization of response 
bodies:
+       <ja>@Response</ja>-annotated types can also be used as value parameters:
 </p>
 <p class='bpcode w800'>
-       <ja>@RestResource</ja>
-       <jk>public class</jk> ExampleResource {
-
-               <jc>// Example 1 - String[] should be serialized using part 
serializer.</jc>
-               <ja>@Response</ja>(
-                       usePartSerializer=<jk>true</jk>
-               )
-               <ja>@RestMethod</ja>
-               <jk>public</jk> String[] example1() {
-                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
-               }
-
-               <jc>// Example 2 - Same as above.  Annotation on parameter.</jc>
-               <ja>@RestMethod</ja>
-               <jk>public void</jk> example2(
-                       <ja>@Response</ja>(
-                               usePartSerializer=<jk>true</jk>
-                       ) 
-                       Value&lt;String[]&gt; body
-               ) 
-               {
-                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
-               }
+       <ja>@RestMethod</ja>(...)
+       <jk>public void</jk> login(
+               ...
+               <ja>@Response</ja> Value&lt;Ok&gt; res
+       ) <jk>throws</jk> InvalidLogin 
+       {
+               ...
+               res.set(<jk>new</jk> Ok());
        }
 </p>
 <p>
-       The <code>usePartSerializer</code> flag is assumed to be <jk>true</jk> 
if you specify <code>schema</code>
-       or <code>partSerializer</code> on the annotation.
+       In the above example, the <ja>@Response</ja> annotation is optional 
since it is inferred from the class
+       that it's a <ja>@Response</ja> bean.
 </p>
 <p class='bpcode w800'>
-       <ja>@RestResource</ja>
-       <jk>public class</jk> ExampleResource {
-
-               <jc>// Example 1 - Part serializer used because schema is 
defined</jc>
-               <ja>@Response</ja>(
-                       
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
-               )
-               <ja>@RestMethod</ja>
-               <jk>public</jk> String[] example1() {
-                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
-               }
-
-               <jc>// Example 2 - Part serializer used because partSerializer 
is defined</jc>
-               <ja>@RestMethod</ja>
-               <jk>public void</jk> example2(
-                       <ja>@Response</ja>(
-                               
partSerializer=OpenApiPartSerializer.<jk>class</jk>
-                       ) 
-                       Value&lt;String[]&gt; body
-               ) 
-               {
-                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
-               }
+       <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+       <jk>public void</jk> login(
+               ...
+               Value&lt;Ok&gt; res  <jc>// @Response annotation not 
needed.</jc>
+       ) <jk>throws</jk> InvalidLogin 
+       {
+               ...
+               res.set(<jk>new</jk> Ok());
        }
 </p>
 
-<h5 class='topic'>@ResponseStatus</h5>
+<h5 class='topic'>@ResponseStatus on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation can be used on 
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify HTTP 
response
+       the method of a <ja>@Response</ja>-annotated class to identify HTTP 
response
        statuses other than <code>200</code> (the default).     
 </p>
 
@@ -268,15 +258,15 @@
 </p>
 
 
-<h5 class='topic'>@ResponseHeader</h5>
+<h5 class='topic'>@ResponseHeader on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation can be used on
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify a header
+       the method of a <ja>@Response</ja>-annotated class to identify a header
        to add to the response.
 </p>
 
 <h5 class='figure'>Example:</h5>
-<p class='bcode w800'>
+<p class='bpcode w800'>
        <ja>@Response</ja>
        <jk>public class</jk> AddPetSuccess {
  
@@ -291,15 +281,15 @@
        }
 </p>
 
-<h5 class='topic'>@ResponseBody</h5>
+<h5 class='topic'>@ResponseBody on methods of @Response-annotated types</h5>
 <p>
        The {@link org.apache.juneau.http.annotation.ResponseBody 
@ResponseBody} annotation can be used on
-       the method of a {@link 
org.apache.juneau.http.annotation.Response}-annotated class to identify a POJO
+       the method of a <ja>@Response</ja>-annotated class to identify a POJO
        as the body of the HTTP response.
 </p>
 
 <h5 class='figure'>Example:</h5>
-<p class='bcode w800'>
+<p class='bpcode w800'>
        <ja>@Response</ja>
        <jk>public class</jk> AddPetSuccess {
  
@@ -313,6 +303,74 @@
        object itself is serialized in the response (typically using 
<code>toString()</code>).
 </p>
 
+<h5 class='topic'>Notes about OpenAPI part serialization</h5>
+<p>
+       By default, POJOs representing the body of the request are serialized 
using the Juneau serializer
+       matching the requesting <code>Accept</code> header.
+       <br>It is also possible to use OpenAPI part serialization for the body 
of the response using 
+       the {@link 
org.apache.juneau.http.annotation.Response#usePartSerializer() 
usePartSerializer} flag.
+       <br>The flag is needed to identify that we should use the part 
serializer instead of normal serializers for the POJO.
+</p>
+<p>
+       The following examples show part-schema-based serialization of response 
bodies:
+</p>
+<p class='bpcode w800'>
+       <ja>@RestResource</ja>
+       <jk>public class</jk> ExampleResource {
+
+               <jc>// Example 1 - String[] should be serialized using part 
serializer.</jc>
+               <ja>@Response</ja>(
+                       usePartSerializer=<jk>true</jk>
+               )
+               <ja>@RestMethod</ja>
+               <jk>public</jk> String[] example1() {
+                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
+               }
+
+               <jc>// Example 2 - Same as above.  Annotation on parameter.</jc>
+               <ja>@RestMethod</ja>
+               <jk>public void</jk> example2(
+                       <ja>@Response</ja>(
+                               usePartSerializer=<jk>true</jk>
+                       ) 
+                       Value&lt;String[]&gt; body
+               ) 
+               {
+                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
+               }
+       }
+</p>
+<p>
+       The <code>usePartSerializer</code> flag is assumed to be <jk>true</jk> 
if you specify <code>schema</code>
+       or <code>partSerializer</code> on the annotation.
+</p>
+<p class='bpcode w800'>
+       <ja>@RestResource</ja>
+       <jk>public class</jk> ExampleResource {
+
+               <jc>// Example 1 - Part serializer used because schema is 
defined</jc>
+               <ja>@Response</ja>(
+                       
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+               )
+               <ja>@RestMethod</ja>
+               <jk>public</jk> String[] example1() {
+                       <jk>return new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>};
+               }
+
+               <jc>// Example 2 - Part serializer used because partSerializer 
is defined</jc>
+               <ja>@RestMethod</ja>
+               <jk>public void</jk> example2(
+                       <ja>@Response</ja>(
+                               
partSerializer=OpenApiPartSerializer.<jk>class</jk>
+                       ) 
+                       Value&lt;String[]&gt; body
+               ) 
+               {
+                       body.set(<jk>new</jk> 
String[]{<js>"foo"</js>,<js>"bar"</js>});
+               }
+       }
+</p>
+
 <h5 class='topic'>Swagger documentation</h5>
 <p>
        The attributes on this annotation are also used to populate the 
generated Swagger for the method.
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/10.ResponseHeader.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/10.ResponseHeader.html
index 3724a0e..2e8d6ed 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/10.ResponseHeader.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/10.ResponseHeader.html
@@ -13,10 +13,10 @@
  
***************************************************************************************************************************/
  -->
 
-{todo} @ResponseHeader
+{new} @ResponseHeader
 
 <p>
-       The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation is applied to parameters and parameter types to 
denote them as an HTTP response headers.
+       The {@link org.apache.juneau.http.annotation.ResponseHeader 
@ResponseHeader} annotation can be applied to <ja>@RestMethod</ja>-annotated 
parameters to denote them as an HTTP response headers.
 </p>
 <ul class='doctree'>
        <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseHeader 
ResponseHeader}
@@ -49,13 +49,7 @@
        </ul>
 </ul>
 <p>
-       It can be used in the following locations:
-</p>
-<ul>
-       <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
-</ul>
-<p>
-       This annotation can only be applied to subclasses or parameters of type 
{@link org.apache.juneau.Value}.
+       This annotation can only be applied to parameters of type {@link 
org.apache.juneau.Value}.
 </p>
 <p>
        The following examples show 3 different ways of accomplishing the same 
task of setting an HTTP header
@@ -88,8 +82,8 @@
 
        <jc>// Example #3 - Use on type.</jc>
        <ja>@RestMethod</ja>(...)
-       <jk>public void</jk> login(RateLimit rateLimit) {
-               rateLimit.set(1000);
+       <jk>public void</jk> login(Value&lt;RateLimit&gt; rateLimit) {
+               rateLimit.set(<jk>new</jk> RateLimit());
                ...
        }
 
@@ -100,7 +94,12 @@
                description=<js>"Calls per hour allowed by the user."</js>, 
                example=<js>"123"</js>
        )
-       <jk>public class</jk> RateLimit <jk>extends</jk> Value&lt;Integer&gt; {}
+       <jk>public class</jk> RateLimit {
+               <jc>// OpenApiPartSerializer knows to look for this method 
based on format/type.</jc>
+               <jk>public</jk> Integer toInteger() {
+                       <jk>return</jk> 1000;
+               }
+       }
 </p>
 
 <h5 class='topic'>Swagger documentation</h5>
diff --git 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/11.ResponseStatus.html
 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/11.ResponseStatus.html
index ce2a7d7..cee1da8 100644
--- 
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/11.ResponseStatus.html
+++ 
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/09.HttpPartAnnotations/11.ResponseStatus.html
@@ -13,35 +13,26 @@
  
***************************************************************************************************************************/
  -->
 
-{todo} @ResponseStatus
+{new} @ResponseStatus
 
 <p>
-       The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation is applied to parameters and parameter 
-       types to denote them as an HTTP response status on server-side REST 
method parameters.
+       The {@link org.apache.juneau.http.annotation.ResponseStatus 
@ResponseStatus} annotation annotation can be applied to 
<ja>@RestMethod</ja>-annotated parameters to denote them as an HTTP response 
status codes.
 </p>
 <ul class='doctree'>
        <li class='ja'>{@link org.apache.juneau.http.annotation.ResponseStatus 
ResponseStatus}
 </ul>
 <p>
-       It can be used in the following locations:
-</p>
-<ul>
-       <li>Java method arguments and argument-types of server-side 
<ja>@RestMethod</ja>-annotated REST Java methods.
-</ul>
-<p>
        This can only be applied to parameters of the {@link 
org.apache.juneau.Value} class with an {@link java.lang.Integer} type.
-       <br>The {@link org.apache.juneau.Value} object is mean to be a 
place-holder for the set value.
 </p>
 
-<h5 class='section'>Examples:</h5>
+<h5 class='figure'>Examples:</h5>
 <p class='bpcode w800'>
        <jc>// Defined on parameter.</jc>
        <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
        <jk>public void</jk> login(
                <ja>@FormData</ja>(<js>"username"</js>) String username, 
                <ja>@FormData</ja>(<js>"password"</js>) String password,
-               <ja>@ResponseStatus</ja> 
-               Value&lt;Integer&gt; status
+               <ja>@ResponseStatus</ja> Value&lt;Integer&gt; status
        ) 
        {
                <jk>if</jk> (! isValid(username, password))

Reply via email to