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 a4daa4f Javadoc updates.
a4daa4f is described below
commit a4daa4f4f329501fac40b602c6d7e7e6bace4af0
Author: JamesBognar <[email protected]>
AuthorDate: Mon Apr 23 20:49:22 2018 -0400
Javadoc updates.
---
.../org/apache/juneau/rest/annotation/Body.java | 7 +
.../apache/juneau/rest/annotation/FormData.java | 7 +
.../org/apache/juneau/rest/annotation/Header.java | 7 +
.../org/apache/juneau/rest/annotation/Path.java | 7 +
.../org/apache/juneau/rest/annotation/Query.java | 7 +
.../apache/juneau/rest/annotation/Response.java | 164 +++++++++++++++++++++
6 files changed, 199 insertions(+)
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java
index 72f5744..f6c8b7c 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java
@@ -326,6 +326,13 @@ public @interface Body {
* The format of the value is a JSON object.
* <br>Multiple lines are concatenated with newlines.
* <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
* Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
* (e.g. <js>"$L{my.localized.variable}"</js>).
* </ul>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/FormData.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/FormData.java
index 267f782..8049a63 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/FormData.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/FormData.java
@@ -370,6 +370,13 @@ public @interface FormData {
* The format of the value is a JSON object.
* <br>Multiple lines are concatenated with newlines.
* <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
* Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
* (e.g. <js>"$L{my.localized.variable}"</js>).
* </ul>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Header.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Header.java
index 8669992..66ecc63 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Header.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Header.java
@@ -343,6 +343,13 @@ public @interface Header {
* The format of the value is a JSON object.
* <br>Multiple lines are concatenated with newlines.
* <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
* Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
* (e.g. <js>"$L{my.localized.variable}"</js>).
* </ul>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
index 6c1ff96..ebe2e14 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Path.java
@@ -291,6 +291,13 @@ public @interface Path {
* The format of the value is a JSON object.
* <br>Multiple lines are concatenated with newlines.
* <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
* Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
* (e.g. <js>"$L{my.localized.variable}"</js>).
* </ul>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
index 6ba842c..dc02856 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Query.java
@@ -366,6 +366,13 @@ public @interface Query {
* The format of the value is a JSON object.
* <br>Multiple lines are concatenated with newlines.
* <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
* Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
* (e.g. <js>"$L{my.localized.variable}"</js>).
* </ul>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
index 45f1624..7f5def4 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java
@@ -17,8 +17,78 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
+import org.apache.juneau.rest.exception.*;
+import org.apache.juneau.rest.helper.*;
+
/**
* Annotation that can be applied to exceptions and return types that identify
the HTTP status they trigger and a description about the exception.
+ *
+ * <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 {@link Unauthorized} for an invalid login attempt.
+ * <br>Note that the annotation can be used on super and subclasses.
+ *
+ * <p class='bcode'>
+ * <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'>
+ * <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 {@link Ok} class which is defined
like so:
+ *
+ * <p class='bcode'>
+ * <ja>@Response</ja>(code=200, example=<js>"'OK'"</js>)
+ * <jk>public class</jk> Ok { ... }
+ * </p>
+ *
+ * <p>
+ * Another example is {@link Redirect} which is defined like so:
+ *
+ * <p class='bcode'>
+ * <ja>@Response<ja>(
+ * code=302,
+ * description=<js>"Redirect"</js>,
+ * headers={<js>"Location:{description:'Redirect URI',
type:'string', format:'uri'}"</js>}
+ * )
+ * <jk>public class</jk> Redirect { ... }
+ * </p>
+ *
+ *
*/
@Documented
@Target(TYPE)
@@ -26,15 +96,109 @@ import java.lang.annotation.*;
@Inherited
public @interface Response {
+ /**
+ * The HTTP response code.
+ *
+ * The default value is <code>500</code> for exceptions and
<code>200</code> for return types.
+ */
int code() default 0;
+ /**
+ * A synonym to {@link #code()}.
+ *
+ * <p>
+ * Useful if you only want to specify a code only.
+ *
+ * <p class='bcode'>
+ * <ja>@Response</ja>(200)
+ * <jk>public class</jk> Ok {...}
+ * </p>
+ */
int value() default 0;
+ /**
+ * Defines the swagger value
<code>/paths/{path}/{method}/responses/{status-code}/description</code>.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format of the value is plain-text.
+ * <br>Multiple lines are concatenated with newlines.
+ * <li>
+ * Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
+ * (e.g. <js>"$L{my.localized.variable}"</js>).
+ * </ul>
+ */
String[] description() default {};
+ /**
+ * Defines the swagger value
<code>/paths/{path}/{method}/responses/{status-code}/schema</code>.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format of the value is a JSON object.
+ * <br>Multiple lines are concatenated with newlines.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
+ *
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
+ * <ul>
+ * <li>
+ * Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
+ * (e.g. <js>"$L{my.localized.variable}"</js>).
+ * </ul>
+ */
String[] schema() default {};
+ /**
+ * Defines the swagger value
<code>/paths/{path}/{method}/responses/{status-code}/headers</code>.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format of the value is a JSON object.
+ * <br>Multiple lines are concatenated with newlines.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>headers=<js>"{Location:{description:'Redirect URI', type:'string',
format:'uri'}}"</js></code>
+ *
<li><code>headers=<js>"Location:{description:'Redirect URI', type:'string',
format:'uri'}"</js></code>
+ * <ul>
+ * <li>
+ * Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
+ * (e.g. <js>"$L{my.localized.variable}"</js>).
+ * </ul>
+ */
String[] headers() default {};
+ /**
+ * Used for populating the Swagger field
<code>/paths/{path}/{method}/responses/{status-code}/x-examples</code>.
+ *
+ * <p>
+ * The format of the example should be a JSON representation of the
POJO being serialized.
+ * <br>This value is parsed from JSON into a POJO using the JSON
parser, then serialized to the various supported
+ * media types for the method using the registered serializers to
produce examples for all supported types.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format of the value is any valid JSON.
+ * <br>Multiple lines are concatenated with newlines.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <ul>
+ *
<li><code>example=<js>"{foo:'bar',baz:123}"</js></code>
+ *
<li><code>example=<js>"foo:'bar',baz:123"</js></code>
+ * <ul>
+ * <li>
+ * Supports <a class="doclink"
href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time
and request-time variables</a>
+ * (e.g. <js>"$L{my.localized.variable}"</js>).
+ * </ul>
+ */
String[] example() default {};
}
--
To stop receiving notification emails like this one, please contact
[email protected].
