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 e32ac7e Javadocs.
e32ac7e is described below
commit e32ac7e2e06a131bc54f20d7e7d45662a093a6f3
Author: JamesBognar <[email protected]>
AuthorDate: Sat Jul 28 16:16:31 2018 -0400
Javadocs.
---
.../apache/juneau/http/annotation/Response.java | 75 +----
juneau-doc/juneau-doc.jar | Bin 12598 -> 12539 bytes
.../apache/juneau/doc/internal/DocGenerator.java | 2 +-
juneau-doc/src/main/javadoc/overview.html | 307 ++++++++++---------
.../25.OpenApiDetails/01.Methodology.html | 2 +-
.../09.HttpPartAnnotations/09.Response.html | 336 ++++++++++-----------
.../src/main/resources/overview-template.html | 12 +-
7 files changed, 324 insertions(+), 410 deletions(-)
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 4f3527a..0c16949 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
@@ -30,83 +30,16 @@ import org.apache.juneau.jsonschema.*;
*
* <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>Java methods of server-side <ja>@RestMethod</ja>-annotated REST
Java methods.
+ * <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.
* </ul>
*
* <p>
* When applied to exception classes, this annotation defines Swagger
information on non-200 return types.
*
- * <p>
- * The following example shows the <ja>@Response</ja> annotation used to
define a subclass of <code>Unauthorized</code> for an invalid login attempt.
- * <br>Note that the annotation can be used on super and subclasses.
- *
- * <p class='bcode w800'>
- * <jc>// Our REST method that throws an annotated exception.</jc>
- * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- * <jk>public</jk> Ok login(String username, String password)
<jk>throws</jk> InvalidLogin {...}
- *
- * <jc>// Our annotated exception.</jc>
- * <ja>@Response</ja>(description=<js>"Invalid username or password
provided"</js>)
- * <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
- * <jk>public</jk> InvalidLogin() {
- * <jk>super</jk>(<js>"Invalid username or
password."</js>); <jc>// Message sent in response</jc>
- * }
- * }
- *
- * <jc>// Parent exception class.</jc>
- * <jc>// Note that the default description is overridden above.</jc>
- * <ja>@Response</ja>(code=401, description=<js>"Unauthorized"</js>)
- * <jk>public class</jk> Unauthorized <jk>extends</jk> RestException { ...
}
- * </p>
- *
- * <p>
- * The attributes on this annotation are used to populate the generated
Swagger for the method.
- * <br>In this case, the Swagger is populated with the following:
- *
- * <p class='bcode w800'>
- * <js>'/user/login'</js>: {
- * get: {
- * responses: {
- * 401: {
- * description: <js>'Invalid username or
password provided'</js>
- * }
- * }
- * }
- * }
- * </p>
- *
- * <p>
- * When applied to return type classes, this annotation defines Swagger
information on the body of responses.
- *
- * <p>
- * In the example above, we're using the <code>Ok</code> class which is
defined like so:
- *
- * <p class='bcode w800'>
- * <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
- * <jk>public class</jk> Ok { ... }
- * </p>
- *
- * <p>
- * Another example is <code>Redirect</code> which is defined like so:
- *
- * <p class='bcode w800'>
- * <ja>@Response</ja>(
- * code=302,
- * description=<js>"Redirect"</js>,
- * headers={
- * <ja>@ResponseHeader</ja>(
- * name=<js>"Location"</js>,
- * type=<js>"string"</js>,
- * format=<js>"uri"</js>
- * )
- * }
- * )
- * <jk>public class</jk> Redirect { ... }
- * </p>
- *
* <h5 class='section'>See Also:</h5>
* <ul>
* <li class='link'><a class="doclink"
href="../../../../../overview-summary.html#juneau-rest-server.HttpPartAnnotations.Response">Overview
> juneau-rest-server > @Response</a>
diff --git a/juneau-doc/juneau-doc.jar b/juneau-doc/juneau-doc.jar
index 2018967..7453ef6 100644
Binary files a/juneau-doc/juneau-doc.jar and b/juneau-doc/juneau-doc.jar differ
diff --git
a/juneau-doc/src/main/java/org/apache/juneau/doc/internal/DocGenerator.java
b/juneau-doc/src/main/java/org/apache/juneau/doc/internal/DocGenerator.java
index bcd86e6..dab4806 100644
--- a/juneau-doc/src/main/java/org/apache/juneau/doc/internal/DocGenerator.java
+++ b/juneau-doc/src/main/java/org/apache/juneau/doc/internal/DocGenerator.java
@@ -105,7 +105,7 @@ public class DocGenerator {
.append("</div>").append("<!-- END:
").append(rf.version).append(" -->\n");
}
- template = template.replace("{TOC-CONTENTS}",
toc.toString()).replace("{CONTENTS}",
contents.toString()).replace("{TOC-RELEASE-NOTES}",
tocRn).replace("{RELEASE-NOTES}", rn);
+ template = template.replace("<!--{TOC-CONTENTS}-->",
toc.toString()).replace("<!--{CONTENTS}-->",
contents.toString()).replace("<!--{TOC-RELEASE-NOTES}-->",
tocRn).replace("<!--{RELEASE-NOTES}-->", rn);
IOUtils.writeFile("src/main/javadoc/overview.html",
template);
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 2e1cd6f..35a1bf7 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -44,8 +44,8 @@
</head>
<body>
<h1 style='background-color:
yellow;color:red;text-align:center;padding:20px;border-radius:15px;'>Apache
Juneau 7.2.0 Documentation Preview</h1>
-<h2 class='todo'
style='text-align:center;padding:10px;border-radius:15px;'>Documentation in
progress</h1>
-<h2 class='new'
style='text-align:center;padding:10px;border-radius:15px;'>New/updated
documentation</h1>
+<h2 class='todo'
style='text-align:center;padding:10px;border-radius:15px;'>Documentation in
progress</h2>
+<h2 class='new'
style='text-align:center;padding:10px;border-radius:15px;'>New/updated
documentation</h2>
<script type='text/javascript'>
function toggle(x) {
@@ -8292,7 +8292,7 @@ TODO(7.2.0)
<td>{@link java.lang.String}</td>
</tr>
<tr class='light bb'>
- <td rowpan='1'><code>boolean</code></td>
+ <td rowspan='1'><code>boolean</code></td>
<td>empty</td>
<td>{@link java.lang.Boolean}</td>
</tr>
@@ -15428,65 +15428,77 @@ VariantAlsoNegotiates
</ul>
</ul>
<p>
- <br>It can be used in the following locations:
+ It can be used in the following locations:
+</p>
<ul>
<li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST
Java methods.
- <li>Type classes returned by <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.
</ul>
+<h5 class='topic'>@Resource on exception classes</h5>
<p>
- When applied to exception classes, this annotation defines Swagger
information on non-200 return types.
+ When applied to an exception class, this annotation defines Swagger
schema and information on non-200 return types.
</p>
<p>
- The following example shows the <ja>@Response</ja> annotation used to
define a subclass of <code>Unauthorized</code> for an invalid login attempt.
+ The following example shows the <ja>@Response</ja> annotation used to
define an exception for an invalid login attempt:
</p>
<p class='bpcode w800'>
- <jc>// Our REST method that throws an annotated exception.</jc>
- <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- <jk>public</jk> Ok login(String username, String password)
<jk>throws</jk> InvalidLogin {
- checkCredentials(username, password);
- <jk>return new</jk> Ok();
- }
-
<jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(description=<js>"Invalid username or password
provided"</js>)
- <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
+ <ja>@Response</ja>(
+ code=401,
+ description=<js>"Invalid username or password provided"</js>
<jc>// Description show in Swagger</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Exception {
<jk>public</jk> InvalidLogin() {
<jk>super</jk>(<js>"Invalid username or
password."</js>); <jc>// Message sent in response</jc>
}
}
- <jc>// Parent exception class.</jc>
- <jc>// Note that the default description is overridden above.</jc>
- <ja>@Response</ja>(code=401, description=<js>"Unauthorized"</js>)
- <jk>public class</jk> Unauthorized <jk>extends</jk> RestException { ...
}
+ <jc>// Our REST method that throws an annotated exception.</jc>
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ <jk>public</jk> Ok login(
+ <ja>@FormData</ja>(<js>"username"</js>) String username,
+ <ja>@FormData</ja>(<js>"password"</js>) String password
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ <jk>return new</jk> Ok();
+ }
</p>
<p>
- The attributes on this annotation are used to populate the generated
Swagger for the method.
- <br>In this case, the Swagger is populated with the following:
+ Custom exception can also extend from one of the predefined HTTP
exceptions such as the {@link org.apache.juneau.rest.exception.Unauthorized}
exception:
</p>
<p class='bpcode w800'>
- <js>'/user/login'</js>: {
- get: {
- responses: {
- 401: {
- description: <js>'Invalid username or
password provided'</js>
- }
- }
+ <jc>// Our annotated exception.</jc>
+ <ja>@Response</ja>(
+ description=<js>"Invalid username or password provided"</js>
<jc>// Overridden from parent class</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
+ <jk>public</jk> InvalidLogin() {
+ <jk>super</jk>(<js>"Invalid username or
password."</js>);
}
}
+
+ <jc>// Parent exception class.</jc>
+ <ja>@Response</ja>(
+ code=401,
+ description=<js>"Unauthorized"</js>
+ )
+ <jk>public class</jk> Unauthorized <jk>extends</jk> RestException {...}
</p>
+
+<h5 class='topic'>@Resource on return type classes</h5>
<p>
- When applied type classes returned by a Java method, this annotation
defines Swagger information on the body of responses.
+ When applied type classes returned by a Java method, this annotation
defines schema and Swagger information on the body of responses.
</p>
<p>
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 { ... }
+ <jk>public class</jk> Ok {...}
</p>
<p>
Another example is <code>Redirect</code> which is defined like so:
@@ -15495,7 +15507,7 @@ VariantAlsoNegotiates
<ja>@Response</ja>(
code=302,
description=<js>"Redirect"</js>,
- headers={
+ headers={ <jc>// Added to Swagger documentation</jc>
<ja>@ResponseHeader</ja>(
name=<js>"Location"</js>,
type=<js>"string"</js>,
@@ -15503,161 +15515,160 @@ VariantAlsoNegotiates
)
}
)
- <jk>public class</jk> Redirect { ... }
+ <jk>public class</jk> Redirect {...}
</p>
+
+<h5 class='topic'>@Resource on @RestMethod-annotated method</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.
+ 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>)
- <jk>public</jk> Ok login(String username, String password)
<jk>throws</jk> InvalidLogin {...}
+ <jk>public</jk> Ok login(
+ <ja>@FormData</ja>(<js>"username"</js>) String username,
+ <ja>@FormData</ja>(<js>"password"</js>) String password
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ <jk>return new</jk> Ok();
+ }
</p>
+
+<h5 class='topic'>@Resource on @RestMethod-annotated method parameter</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.utils.Value} (a placeholder for objects).
+ is {@link org.apache.juneau.Value} (a placeholder for objects).
</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>)
<jk>public void</jk> login(
- String username,
- String password,
- <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
Value<Object>
- ) <jk>throws</jk> InvalidLogin {...}
+ <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<String> body
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ body.set(<js>"OK"</js>);
+ }
</p>
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
-
+<h5 class='topic'>Automatic HTTP status</h5>
<p>
- Any of the following types can be used for the parameter or POJO class
(matched in the specified order):
+ When the {@link org.apache.juneau.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.
</p>
-<ol class='spaced-list'>
- <li>
- {@link java.io.Reader}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- {@link java.io.InputStream}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- Any <a class='doclink'
href='#juneau-marshall.PojoCategories'>Parsable POJO</a> type.
- <br><code>Content-Type</code> is required to identify correct
parser.
- <li>
- Objects convertible from {@link java.io.Reader} by having one
of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(Reader in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(Reader in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromReader</jsm>(Reader in) {...}</code>
- </ul>
- <code>Content-Type</code> must not be present or match an
existing parser so that it's not parsed as a POJO.
- <li>
- Objects convertible from {@link java.io.InputStream} by having
one of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(InputStream in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(InputStream in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromInputStream</jsm>(InputStream in) {...}</code>
- </ul>
- <code>Content-Type</code> must not be present or match an
existing parser so that it's not parsed as a POJO.
- <li>
- Objects convertible from {@link java.lang.String} by having one
of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromString</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>parse</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>parseString</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>forName</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>forString</jsm>(String in) {...}</code>
- </ul>
- Note that this also includes all enums.
-</ol>
<p>
- If the {@link org.apache.juneau.http.annotation.Body#usePartParser
usePartParser} flag is set on the annotation,
- then the body can be parsed using the registered {@link
org.apache.juneau.httppart.HttpPartParser} which by default
- is {@link org.apache.juneau.httppart.OpenApiPartParser}.
+ The following two examples are equivalent:
</p>
-<p>
- For example, the following shows how a pipe-delimited list of
comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to
a 2-dimensional array of <code>Longs</code>:
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/ok"</js>)
+ <jk>public void</jk> sendContinue(
+ <ja>@Response</ja>(code=100) Value<String> body
+ )
+ {
+ body.set(<js>"OK"</js>);
+ }
</p>
<p class='bpcode w800'>
- <jc>// Body is a pipe-delimited list of comma-delimited lists of
longs.</jc>
- <ja>@RestMethod</ja>(method=<js>"POST"</js>, path=<js>"/testBody"</js>)
- <jk>public void</jk> testBody(
- <ja>@Body</ja>(
- usePartParser=<jk>true</jk>,
- schema=<ja>@Schema</ja>(
- items=<ja>@Items</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- )
- ),
- minLength=1,
- maxLength=10
- )
- )
- Long[][] body
- ) {...}
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/ok"</js>)
+ <jk>public void</jk> sendContinue(RestResponse res) {
+ res.setStatus(100);
+ res.setOutput(<js>"OK"</js>);
+ }
</p>
+
+<h5 class='topic'>OpenAPI part serialization</h5>
<p>
- Input will be converted based on the types and formats defined in the
schema definition.
- <br>Input validations such as <code>minLength/maxLength</code> that
don't match the input will result in automatic <code>400 Bad Request</code>
responses.
+ 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.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>
- For more information about valid parameter types when using OpenAPI
parsing, see <a class='doclink'
href='#juneau-marshall.OpenApiDetails.Parsers'>OpenAPI Parsers</a>
+ The following examples show part-schema-based serialization of response
bodies:
</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>
+ <jk>public class</jk> ExampleResource {
-<p>
- The <ja>@Body</ja> annotation is also used for supplying swagger
information about the body of the request.
- <br>This information is used to populate the auto-generated Swagger
documentation and UI.
+ <jc>// Example 1 - Pipe-delimited array of strings. Annotation
on method.</jc>
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+ )
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example1"</js>)
+ <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>(name=<jsf>GET</jsf>,path=<js>"/example2"</js>)
+ <jk>public void</jk> example2(
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+ )
+ Value<String[]> body
+ )
+ {
+ body.set(<jk>new</jk>
String[]{<js>"foo"</js>,<js>"bar"</js>});
+ }
+
+ <jc>// Example 3 - BASE64-encoded byte array. Annotation on
method.</jc>
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(type=<js>"string"</js>,format=<js>"byte"</js>)
+ )
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example3"</js>)
+ <jk>public byte</jk>[] example3() {
+ <jk>return</jk> <js>"foo"</js>.getBytes();
+ }
+
+ <jc>// Example 4 - Same as above. Annotation on parameter.</jc>
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example4"</js>)
+ <jk>public void</jk> example4(
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(type=<js>"string"</js>,format=<js>"byte"</js>)
+ )
+ Value<<jk>byte</jk>[]> body
+ )
+ {
+ body.set(<js>"foo"</js>.getBytes());
+ }
+ }
</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Normal</jc>
- <ja>@Body</ja>(
- description=<js>"Pet object to add to the store"</js>,
- required=<jk>true</jk>,
-
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- )
+<p>
+ When using part serialization, any of the types defined in <a
class='doclink' href='#juneau-marshall.OpenApiDetails.Serializers'>OpenAPI
Serializers</a> can
+ be used as the POJO type.
</p>
-<p class='bpcode w800'>
- <jc>// Free-form</jc>
- <jc>// Note the extra field</jc>
- <ja>@Body</ja>({
- <js>"description: 'Pet object to add to the store',"</js>,
- <js>"required: true,"</js>,
- <js>"example:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']},"</js>
- <js>"x-extra: 'extra field'"</js>
- })
+<p>
+ Part serialization can also be used on exception classes as well.
</p>
+
+<h5 class='topic'>Swagger documentation</h5>
<p>
- <a class='doclink' href='#DefaultRestSvlVariables'>Initialization and
request-time variables</a> (e.g. "$L{my.localized.variable}")
- are supported on annotation fields.
+ The attributes on this annotation are also used to populate the
generated Swagger for the method.
+ <br>For example, in the case of the <code>InvalidLogin</code> example
above, the following Swagger is generated:
</p>
-<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
- <jc>// Localized</jc>
- <ja>@Body</ja>(
- description=<js>"$L{PetObjectDescription}"</js>
- )
+ <js>'/user/login'</js>: {
+ get: {
+ responses: {
+ 401: {
+ description: <js>'Invalid username or
password provided'</js>
+ }
+ }
+ }
+ }
</p>
-
-
<h5 class='section'>See Also:</h5>
<ul>
- <li class='jc'>{@link org.apache.juneau.rest.RequestBody}
<li class='link'><a class='doclink'
href='#juneau-rest-server.OpenApiSchemaPartSerializing'>OpenAPI Schema Part
Serializing</a>
</ul>
</div><!-- END: 7.9.9 - juneau-rest-server.HttpPartAnnotations.Response -->
diff --git
a/juneau-doc/src/main/resources/Topics/02.juneau-marshall/25.OpenApiDetails/01.Methodology.html
b/juneau-doc/src/main/resources/Topics/02.juneau-marshall/25.OpenApiDetails/01.Methodology.html
index 7c85005..dfb0ae7 100644
---
a/juneau-doc/src/main/resources/Topics/02.juneau-marshall/25.OpenApiDetails/01.Methodology.html
+++
b/juneau-doc/src/main/resources/Topics/02.juneau-marshall/25.OpenApiDetails/01.Methodology.html
@@ -43,7 +43,7 @@
<td>{@link java.lang.String}</td>
</tr>
<tr class='light bb'>
- <td rowpan='1'><code>boolean</code></td>
+ <td rowspan='1'><code>boolean</code></td>
<td>empty</td>
<td>{@link java.lang.Boolean}</td>
</tr>
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 16b892c..4209093 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
@@ -34,65 +34,77 @@
</ul>
</ul>
<p>
- <br>It can be used in the following locations:
+ It can be used in the following locations:
+</p>
<ul>
<li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST
Java methods.
- <li>Type classes returned by <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.
</ul>
+<h5 class='topic'>@Resource on exception classes</h5>
<p>
- When applied to exception classes, this annotation defines Swagger
information on non-200 return types.
+ When applied to an exception class, this annotation defines Swagger
schema and information on non-200 return types.
</p>
<p>
- The following example shows the <ja>@Response</ja> annotation used to
define a subclass of <code>Unauthorized</code> for an invalid login attempt.
+ The following example shows the <ja>@Response</ja> annotation used to
define an exception for an invalid login attempt:
</p>
<p class='bpcode w800'>
- <jc>// Our REST method that throws an annotated exception.</jc>
- <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- <jk>public</jk> Ok login(String username, String password)
<jk>throws</jk> InvalidLogin {
- checkCredentials(username, password);
- <jk>return new</jk> Ok();
- }
-
<jc>// Our annotated exception.</jc>
- <ja>@Response</ja>(description=<js>"Invalid username or password
provided"</js>)
- <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
+ <ja>@Response</ja>(
+ code=401,
+ description=<js>"Invalid username or password provided"</js>
<jc>// Description show in Swagger</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Exception {
<jk>public</jk> InvalidLogin() {
<jk>super</jk>(<js>"Invalid username or
password."</js>); <jc>// Message sent in response</jc>
}
}
- <jc>// Parent exception class.</jc>
- <jc>// Note that the default description is overridden above.</jc>
- <ja>@Response</ja>(code=401, description=<js>"Unauthorized"</js>)
- <jk>public class</jk> Unauthorized <jk>extends</jk> RestException { ...
}
+ <jc>// Our REST method that throws an annotated exception.</jc>
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ <jk>public</jk> Ok login(
+ <ja>@FormData</ja>(<js>"username"</js>) String username,
+ <ja>@FormData</ja>(<js>"password"</js>) String password
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ <jk>return new</jk> Ok();
+ }
</p>
<p>
- The attributes on this annotation are used to populate the generated
Swagger for the method.
- <br>In this case, the Swagger is populated with the following:
+ Custom exception can also extend from one of the predefined HTTP
exceptions such as the {@link org.apache.juneau.rest.exception.Unauthorized}
exception:
</p>
<p class='bpcode w800'>
- <js>'/user/login'</js>: {
- get: {
- responses: {
- 401: {
- description: <js>'Invalid username or
password provided'</js>
- }
- }
+ <jc>// Our annotated exception.</jc>
+ <ja>@Response</ja>(
+ description=<js>"Invalid username or password provided"</js>
<jc>// Overridden from parent class</jc>
+ )
+ <jk>public class</jk> InvalidLogin <jk>extends</jk> Unauthorized {
+ <jk>public</jk> InvalidLogin() {
+ <jk>super</jk>(<js>"Invalid username or
password."</js>);
}
}
+
+ <jc>// Parent exception class.</jc>
+ <ja>@Response</ja>(
+ code=401,
+ description=<js>"Unauthorized"</js>
+ )
+ <jk>public class</jk> Unauthorized <jk>extends</jk> RestException {...}
</p>
+
+<h5 class='topic'>@Resource on return type classes</h5>
<p>
- When applied type classes returned by a Java method, this annotation
defines Swagger information on the body of responses.
+ When applied type classes returned by a Java method, this annotation
defines schema and Swagger information on the body of responses.
</p>
<p>
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 { ... }
+ <jk>public class</jk> Ok {...}
</p>
<p>
Another example is <code>Redirect</code> which is defined like so:
@@ -101,7 +113,7 @@
<ja>@Response</ja>(
code=302,
description=<js>"Redirect"</js>,
- headers={
+ headers={ <jc>// Added to Swagger documentation</jc>
<ja>@ResponseHeader</ja>(
name=<js>"Location"</js>,
type=<js>"string"</js>,
@@ -109,202 +121,160 @@
)
}
)
- <jk>public class</jk> Redirect { ... }
+ <jk>public class</jk> Redirect {...}
</p>
+
+<h5 class='topic'>@Resource on @RestMethod-annotated method</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.
+ 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>)
- <jk>public</jk> Ok login(String username, String password)
<jk>throws</jk> InvalidLogin {...}
+ <jk>public</jk> Ok login(
+ <ja>@FormData</ja>(<js>"username"</js>) String username,
+ <ja>@FormData</ja>(<js>"password"</js>) String password
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ <jk>return new</jk> Ok();
+ }
</p>
+
+<h5 class='topic'>@Resource on @RestMethod-annotated method parameter</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.utils.Value} (a placeholder for objects).
+ is {@link org.apache.juneau.Value} (a placeholder for objects).
</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>)
<jk>public void</jk> login(
- String username,
- String password,
- <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
Value<Object>
- ) <jk>throws</jk> InvalidLogin {...}
+ <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<String> body
+ ) <jk>throws</jk> InvalidLogin
+ {
+ checkCredentials(username, password);
+ body.set(<js>"OK"</js>);
+ }
</p>
-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-
-
-
+<h5 class='topic'>Automatic HTTP status</h5>
+<p>
+ When the {@link org.apache.juneau.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.
+</p>
<p>
- The return type can be any serializable POJO as defined in <a
class='doclink' href='#juneau-marshall.PojoCategories'>POJO Categories</a>.
- <br>It can also be <jk>void</jk> if the method is not sending any
output (e.g. a request redirect) or is
- setting the output using the {@link
org.apache.juneau.rest.RestResponse#setOutput(Object)} method.
+ The following two examples are equivalent:
</p>
-<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
- <ja>@RestMethod</ja>(name=<jsf>GET</jsf>)
- <jk>public</jk> String doGet() {
- <jk>return</jk> <js>"Hello World!"</js>;
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/ok"</js>)
+ <jk>public void</jk> sendContinue(
+ <ja>@Response</ja>(code=100) Value<String> body
+ )
+ {
+ body.set(<js>"OK"</js>);
}
</p>
-<p>
- Out-of-the-box, besides POJOs, the following return types are handled
as special cases:
-</p>
-<ul class='spaced-list'>
- <li class='jc'>{@link java.io.InputStream}
- <br>The contents are simply piped to the output stream returned
by
- {@link
org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}.
- <br>Note that you should call {@link
org.apache.juneau.rest.RestResponse#setContentType(String)} to set
- the <l>Content-Type</l> header if you use this object type.
- <li class='jc'>{@link java.io.InputStream}
- <br>The contents are simply piped to the output stream returned
by
- {@link
org.apache.juneau.rest.RestResponse#getNegotiatedOutputStream()}.
- <br>Note that you should call {@link
org.apache.juneau.rest.RestResponse#setContentType(String)} to set
- the <l>Content-Type</l> header if you use this object type.
- <li class='jc'>{@link java.io.Reader}
- <br>The contents are simply piped to the output stream returned
by
- {@link
org.apache.juneau.rest.RestResponse#getNegotiatedWriter()}.
- <br>Note that you should call {@link
org.apache.juneau.rest.RestResponse#setContentType(String)} to set
- the <l>Content-Type</l> header if you use this object type.
- <li class='jc'>{@link org.apache.juneau.rest.helper.Redirect}
- <br>Represents an HTTP redirect response.
- <li class='jc'>{@link org.apache.juneau.Streamable}
- <br>Interface that identifies that an object can be serialized
directly to an output stream.
- <li class='jc'>{@link org.apache.juneau.Writable}
- <br>Interface that identifies that an object can be serialized
directly to a writer.
- <li class='jc'>{@link org.apache.juneau.utils.ZipFileList}
- <br>Special interface for sending zip files as responses.
-</ul>
-<p>
- Any of the following types can be used for the parameter or POJO class
(matched in the specified order):
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/ok"</js>)
+ <jk>public void</jk> sendContinue(RestResponse res) {
+ res.setStatus(100);
+ res.setOutput(<js>"OK"</js>);
+ }
</p>
-<ol class='spaced-list'>
- <li>
- {@link java.io.Reader}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- {@link java.io.InputStream}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- Any <a class='doclink'
href='#juneau-marshall.PojoCategories'>Parsable POJO</a> type.
- <br><code>Content-Type</code> is required to identify correct
parser.
- <li>
- Objects convertible from {@link java.io.Reader} by having one
of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(Reader in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(Reader in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromReader</jsm>(Reader in) {...}</code>
- </ul>
- <code>Content-Type</code> must not be present or match an
existing parser so that it's not parsed as a POJO.
- <li>
- Objects convertible from {@link java.io.InputStream} by having
one of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(InputStream in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(InputStream in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromInputStream</jsm>(InputStream in) {...}</code>
- </ul>
- <code>Content-Type</code> must not be present or match an
existing parser so that it's not parsed as a POJO.
- <li>
- Objects convertible from {@link java.lang.String} by having one
of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>create</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>fromString</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>parse</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>parseString</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>forName</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T
<jsm>forString</jsm>(String in) {...}</code>
- </ul>
- Note that this also includes all enums.
-</ol>
+
+<h5 class='topic'>OpenAPI part serialization</h5>
<p>
- If the {@link org.apache.juneau.http.annotation.Body#usePartParser
usePartParser} flag is set on the annotation,
- then the body can be parsed using the registered {@link
org.apache.juneau.httppart.HttpPartParser} which by default
- is {@link org.apache.juneau.httppart.OpenApiPartParser}.
+ 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.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>
- For example, the following shows how a pipe-delimited list of
comma-delimited numbers (e.g. <js>"1,2,3|4,5,6|7,8,9"</js>) can be converted to
a 2-dimensional array of <code>Longs</code>:
+ The following examples show part-schema-based serialization of response
bodies:
</p>
<p class='bpcode w800'>
- <jc>// Body is a pipe-delimited list of comma-delimited lists of
longs.</jc>
- <ja>@RestMethod</ja>(method=<js>"POST"</js>, path=<js>"/testBody"</js>)
- <jk>public void</jk> testBody(
- <ja>@Body</ja>(
- usePartParser=<jk>true</jk>,
- schema=<ja>@Schema</ja>(
- items=<ja>@Items</ja>(
- collectionFormat=<js>"pipes"</js>,
- items=<ja>@SubItems</ja>(
- collectionFormat=<js>"csv"</js>,
- type=<js>"integer"</js>,
- format=<js>"int64"</js>,
- minimum=<js>"0"</js>,
- maximum=<js>"100"</js>
- minLength=1,
- maxLength=10
- )
- ),
- minLength=1,
- maxLength=10
- )
+ <ja>@RestResource</ja>
+ <jk>public class</jk> ExampleResource {
+
+ <jc>// Example 1 - Pipe-delimited array of strings. Annotation
on method.</jc>
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+ )
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example1"</js>)
+ <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>(name=<jsf>GET</jsf>,path=<js>"/example2"</js>)
+ <jk>public void</jk> example2(
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(collectionFormat=<js>"pipes"</js>)
+ )
+ Value<String[]> body
+ )
+ {
+ body.set(<jk>new</jk>
String[]{<js>"foo"</js>,<js>"bar"</js>});
+ }
+
+ <jc>// Example 3 - BASE64-encoded byte array. Annotation on
method.</jc>
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(type=<js>"string"</js>,format=<js>"byte"</js>)
)
- Long[][] body
- ) {...}
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example3"</js>)
+ <jk>public byte</jk>[] example3() {
+ <jk>return</jk> <js>"foo"</js>.getBytes();
+ }
+
+ <jc>// Example 4 - Same as above. Annotation on parameter.</jc>
+
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>,path=<js>"/example4"</js>)
+ <jk>public void</jk> example4(
+ <ja>@Response</ja>(
+ usePartSerializer=<jk>true</jk>,
+
schema=<ja>@Schema</ja>(type=<js>"string"</js>,format=<js>"byte"</js>)
+ )
+ Value<<jk>byte</jk>[]> body
+ )
+ {
+ body.set(<js>"foo"</js>.getBytes());
+ }
+ }
</p>
<p>
- Input will be converted based on the types and formats defined in the
schema definition.
- <br>Input validations such as <code>minLength/maxLength</code> that
don't match the input will result in automatic <code>400 Bad Request</code>
responses.
+ When using part serialization, any of the types defined in <a
class='doclink' href='#juneau-marshall.OpenApiDetails.Serializers'>OpenAPI
Serializers</a> can
+ be used as the POJO type.
</p>
<p>
- For more information about valid parameter types when using OpenAPI
parsing, see <a class='doclink'
href='#juneau-marshall.OpenApiDetails.Parsers'>OpenAPI Parsers</a>
+ Part serialization can also be used on exception classes as well.
</p>
+<h5 class='topic'>Swagger documentation</h5>
<p>
- The <ja>@Body</ja> annotation is also used for supplying swagger
information about the body of the request.
- <br>This information is used to populate the auto-generated Swagger
documentation and UI.
-</p>
-<h5 class='figure'>Examples:</h5>
-<p class='bpcode w800'>
- <jc>// Normal</jc>
- <ja>@Body</ja>(
- description=<js>"Pet object to add to the store"</js>,
- required=<jk>true</jk>,
-
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- )
-</p>
-<p class='bpcode w800'>
- <jc>// Free-form</jc>
- <jc>// Note the extra field</jc>
- <ja>@Body</ja>({
- <js>"description: 'Pet object to add to the store',"</js>,
- <js>"required: true,"</js>,
- <js>"example:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']},"</js>
- <js>"x-extra: 'extra field'"</js>
- })
-</p>
-<p>
- <a class='doclink' href='#DefaultRestSvlVariables'>Initialization and
request-time variables</a> (e.g. "$L{my.localized.variable}")
- are supported on annotation fields.
+ The attributes on this annotation are also used to populate the
generated Swagger for the method.
+ <br>For example, in the case of the <code>InvalidLogin</code> example
above, the following Swagger is generated:
</p>
-<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
- <jc>// Localized</jc>
- <ja>@Body</ja>(
- description=<js>"$L{PetObjectDescription}"</js>
- )
+ <js>'/user/login'</js>: {
+ get: {
+ responses: {
+ 401: {
+ description: <js>'Invalid username or
password provided'</js>
+ }
+ }
+ }
+ }
</p>
-
-
<h5 class='section'>See Also:</h5>
<ul>
- <li class='jc'>{@link org.apache.juneau.rest.RequestBody}
<li class='link'><a class='doclink'
href='#juneau-rest-server.OpenApiSchemaPartSerializing'>OpenAPI Schema Part
Serializing</a>
</ul>
diff --git a/juneau-doc/src/main/resources/overview-template.html
b/juneau-doc/src/main/resources/overview-template.html
index ba2f45f..1f6902b 100644
--- a/juneau-doc/src/main/resources/overview-template.html
+++ b/juneau-doc/src/main/resources/overview-template.html
@@ -44,8 +44,8 @@
</head>
<body>
<h1 style='background-color:
yellow;color:red;text-align:center;padding:20px;border-radius:15px;'>Apache
Juneau 7.2.0 Documentation Preview</h1>
-<h2 class='todo'
style='text-align:center;padding:10px;border-radius:15px;'>Documentation in
progress</h1>
-<h2 class='new'
style='text-align:center;padding:10px;border-radius:15px;'>New/updated
documentation</h1>
+<h2 class='todo'
style='text-align:center;padding:10px;border-radius:15px;'>Documentation in
progress</h2>
+<h2 class='new'
style='text-align:center;padding:10px;border-radius:15px;'>New/updated
documentation</h2>
<script type='text/javascript'>
function toggle(x) {
@@ -81,19 +81,19 @@
<a href='#TOC' id='TOC'></a><h5 class='toc'>Table of Contents</h5>
<ol class='toc'>
-{TOC-CONTENTS}
+<!--{TOC-CONTENTS}-->
</ol>
-{CONTENTS}
+<!--{CONTENTS}-->
<h2 class='topic' onclick='toggle(this)'><a href='#ReleaseNotes'
id='ReleaseNotes'>Release Notes</a></h2>
<div class='topic'>
<h5 class='toc'>Release Notes</h5>
<ul class='toc'>
- {TOC-RELEASE-NOTES}
+ <!--{TOC-RELEASE-NOTES}-->
</ul>
- {RELEASE-NOTES}
+ <!--{RELEASE-NOTES}-->
</div>
</body>
