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 ac4c17e Javadocs.
ac4c17e is described below
commit ac4c17e15770e14646b3ba9058677d22f01a9798
Author: JamesBognar <[email protected]>
AuthorDate: Mon Jun 11 20:33:16 2018 -0400
Javadocs.
---
.../org/apache/juneau/rest/annotation/Body.java | 10 ++++--
.../org/apache/juneau/rest/annotation/Contact.java | 13 +++++--
.../juneau/rest/annotation/ExternalDocs.java | 11 +++++-
.../apache/juneau/rest/annotation/FormData.java | 23 +++++++++++++
.../apache/juneau/rest/annotation/HasFormData.java | 17 +++++++++
.../apache/juneau/rest/annotation/HasQuery.java | 17 +++++++++
.../org/apache/juneau/rest/annotation/Header.java | 16 +++++++++
.../org/apache/juneau/rest/annotation/Path.java | 33 +++++++++++++++++-
.../org/apache/juneau/rest/annotation/Query.java | 24 +++++++++++++
.../apache/juneau/rest/annotation/Response.java | 17 +++++++++
.../juneau/rest/annotation/ResponseHeader.java | 40 +++++++++-------------
.../juneau/rest/annotation/ResponseStatus.java | 7 +++-
.../org/apache/juneau/rest/annotation/Tag.java | 33 +++++++++++++++---
13 files changed, 226 insertions(+), 35 deletions(-)
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 cbc434e..8738abb 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
@@ -200,11 +200,10 @@ public @interface Body {
* <li>
* The format is plain text.
* <br>Multiple lines are concatenated with newlines.
+ * <br>TODO - Future support for <a
href='https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown'>MarkDown</a>.
* <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>).
- * <li>
- * TODO - Future support for MarkDown.
* </ul>
*/
String[] description() default {};
@@ -251,6 +250,13 @@ public @interface Body {
/**
* <mk>schema</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#parameterObject";>Parameter</a>
object.
*
+ * <p>
+ * The schema defining the type used for the body parameter.
+ *
+ * <p>
+ * This is a required attribute per the swagger definition.
+ * However, if not explicitly specified, the value will be
auto-generated using {@link JsonSchemaSerializer}.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Contact.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Contact.java
index 5dc12cf..af9cfc4 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Contact.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Contact.java
@@ -64,6 +64,9 @@ public @interface Contact {
/**
* <mk>name</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#contactObject";>Contact</a> object.
*
+ * <p>
+ * The identifying name of the contact person/organization.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
@@ -78,10 +81,13 @@ public @interface Contact {
/**
* <mk>url</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#contactObject";>Contact</a> object.
*
+ * <p>
+ * The URL pointing to the contact information. MUST be in the format
of a URL.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * The format is a plain-text string.
+ * The format is a URL string.
* <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>).
@@ -92,10 +98,13 @@ public @interface Contact {
/**
* <mk>email</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#contactObject";>Contact</a> object.
*
+ * <p>
+ * The email address of the contact person/organization. MUST be in the
format of an email address.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * The format is a plain-text string.
+ * The format is an email string.
* <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>).
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ExternalDocs.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ExternalDocs.java
index f205b8f..e213bd3 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ExternalDocs.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ExternalDocs.java
@@ -25,11 +25,15 @@ public @interface ExternalDocs {
/**
* <mk>description</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#externalDocumentationObject";>ExternalDocumentation</a>
object.
*
+ * <p>
+ * A short description of the target documentation.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
* The format is a plain-text string.
* <br>Multiple lines are concatenated with newlines.
+ * <br>TODO - Future support for <a
href='https://guides.github.com/features/mastering-markdown/#GitHub-flavored-markdown'>MarkDown</a>.
* <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>).
@@ -40,10 +44,15 @@ public @interface ExternalDocs {
/**
* <mk>url</mk> field of the Swagger <a class="doclink"
href="https://swagger.io/specification/v2/#externalDocumentationObject";>ExternalDocumentation</a>
object.
*
+ * <p>
+ * The URL for the target documentation. Value MUST be in the format of
a URL.
+ *
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * The format is a plain-text string.
+ * The value is required.
+ * <li>
+ * The format is a URL string.
* <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>).
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 3b02e25..eabd800 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
@@ -83,9 +83,32 @@ public @interface FormData {
/**
* FORM parameter name.
+ *
+ * Required. The name of the parameter. Parameter names are case
sensitive.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is plain-text.
+ * </ul>
*/
String name() default "";
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining a form post
entry:
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@FormData</jk>(name=<js>"petId"</jk>) <jk>long</jk> petId) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@FormData</jk>(<js>"petId"</js>) <jk>long</jk> petId) {...}
+ * </p>
+ */
String value() default "";
/**
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
index 0bc4867..498b125 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasFormData.java
@@ -97,6 +97,14 @@ public @interface HasFormData {
/**
* FORM parameter name.
+ *
+ * Required. The name of the parameter. Parameter names are case
sensitive.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is plain-text.
+ * </ul>
*/
String name() default "";
@@ -105,6 +113,15 @@ public @interface HasFormData {
*
* <p>
* Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the
existence of a form post entry:
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@HasFormData</jk>(name=<js>"petId"</js>) <jk>boolean</jk>
hasPetId) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@HasFormData</jk>(<js>"petId"</js>) <jk>boolean</jk> hasPetId)
{...}
+ * </p>
*/
String value() default "";
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
index 8dfb9ba..c1e4664 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/HasQuery.java
@@ -60,6 +60,14 @@ public @interface HasQuery {
/**
* URL query parameter name.
+ *
+ * Required. The name of the parameter. Parameter names are case
sensitive.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is plain-text.
+ * </ul>
*/
String name() default "";
@@ -68,6 +76,15 @@ public @interface HasQuery {
*
* <p>
* Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the
existence of a query entry:
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@HasQuery</jk>(name=<js>"petId"</js>) <jk>boolean</jk> hasPetId)
{...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@HasQuery</jk>(<js>"petId"</js>) <jk>boolean</jk> hasPetId) {...}
+ * </p>
*/
String value() default "";
}
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 81c9a63..be540a4 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
@@ -58,6 +58,22 @@ public @interface Header {
* HTTP header name.
*/
String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining a header
entry:
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@Header</jk>(name=<js>"api_key"</js>) String apiKey) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@Header</jk>(<js>"api_key"</js>) String apiKey) {...}
+ * </p>
+ */
String value() default "";
/**
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 9d7fbb3..8f394ce 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
@@ -49,9 +49,40 @@ public @interface Path {
* URL path variable name.
*
* <p>
- * Optional if the attributes are specified in the same order as in the
URL path pattern.
+ * The name field MUST correspond to the associated <a
href='https://swagger.io/specification/v2/#pathsPath'>path</a> segment from the
path field in the <a
href='https://swagger.io/specification/v2/#pathsObject'>Paths Object</a>.
+ * See <a
href='https://swagger.io/specification/v2/#pathTemplating'>Path Templating</a>
for further information.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is plain-text.
+ * </ul>
*/
String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining a path
entry:
+ * <p class='bcode w800'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"GET"</js>,
+ * path=<js>"/pet/{petId}"</js>
+ * )
+ * <jk>public</jk> Pet
getPet(<ja>@Path</ja>(name=<js>"petId"</js>) <jk>long</jk> petId) { ... }
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"GET"</js>,
+ * path=<js>"/pet/{petId}"</js>
+ * )
+ * <jk>public</jk> Pet getPet(<ja>@Path</ja>(<js>"petId"</js>)
<jk>long</jk> petId) { ... }
+ * </p>
+ */
String value() default "";
/**
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 5c5be57..532ba93 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
@@ -79,8 +79,32 @@ public @interface Query {
/**
* URL query parameter name.
+ *
+ * Required. The name of the parameter. Parameter names are case
sensitive.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is plain-text.
+ * </ul>
*/
String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the
existence of a query entry:
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@Query</jk>(name=<js>"petId"</js>) <jk>long</jk> petId) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jk>public</jk> Order
placeOrder(<jk>@Query</jk>(<js>"petId"</js>) <jk>long</jk> petId) {...}
+ * </p>
+ */
String value() default "";
/**
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 a7512f4..2e357c3 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
@@ -112,6 +112,23 @@ public @interface Response {
*/
int code() default 0;
+ /**
+ * A synonym for {@link #code()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
code.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the
response code:
+ * <p class='bcode w800'>
+ * <ja>@Response</ja>(code=404)
+ * <jk>public class</jk> NotFound <jk>extends</jk> RestException
{...}
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Response</ja>(404)
+ * <jk>public class</jk> NotFound <jk>extends</jk> RestException
{...}
+ * </p>
+ */
int value() default 0;
/**
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseHeader.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseHeader.java
index 8ace2b3..04d9c54 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseHeader.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseHeader.java
@@ -103,34 +103,28 @@ public @interface ResponseHeader {
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * At least one of {@link #name()} or {@link #value()}
must be specified}.
+ * The format is plain-text.
* </ul>
*/
String name() default "";
+
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining a response
header:
+ * <p class='bcode w800'>
+ * <ja>@ResponseHeader</ja>(name=<js>"X-Rate-Limit"</js>)
Value<Integer> rateLimit)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@ResponseHeader</ja>(<js>"X-Rate-Limit"</js>)
Value<Integer> rateLimit)
+ * </p>
+ */
String value() default "";
-// /**
-// * A synonym to {@link #name()}.
-// *
-// * <p>
-// * Useful if you only want to specify a header name.
-// *
-// * <p class='bcode'>
-// * <ja>@RestMethod</ja>(...)
-// * <jk>public void</jk>
login(<ja>@ResponseHeader</ja>(<js>"X-Rate-Limit"</js>) Value<Integer>
rateLimit) {
-// * rateLimit.set(1000);
-// * ...
-// * }
-// * </p>
-// *
-// * <h5 class='section'>Notes:</h5>
-// * <ul class='spaced-list'>
-// * <li>
-// * At least one of {@link #name()} or {@link #value()}
must be specified}.
-// * </ul>
-// */
-// String value() default "";
-
/**
* Specifies the {@link HttpPartSerializer} class used for serializing
values.
*
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
index 95f03c8..66021b2 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
@@ -114,7 +114,12 @@ public @interface ResponseStatus {
* <p>
* Useful if you only want to specify a code only.
*
- * <p class='bcode'>
+ * <p>
+ * The following are completely equivalent ways of defining the
response code:
+ * <p class='bcode w800'>
+ * <ja>@ResponseStatus</ja>(code=200)
+ * </p>
+ * <p class='bcode w800'>
* <ja>@ResponseStatus</ja>(200)
* </p>
*/
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Tag.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Tag.java
index 85a9c2a..356e5bf 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Tag.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Tag.java
@@ -43,15 +43,38 @@ public @interface Tag {
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * The format is a JSON object.
- * <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>).
+ * The format is plain text.
* </ul>
*/
String name() default "";
+ /**
+ * A synonym for {@link #name()}.
+ *
+ * <p>
+ * Allows you to use shortened notation if you're only specifying the
name.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining a simple
tag:
+ * <p class='bcode w800'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * tags={
+ * <ja>@Tag</ja>(name=<js>"store"</js>)
+ * }
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * tags={
+ * <ja>@Tag</ja>(<js>"store"</js>)
+ * }
+ * )
+ * )
+ * </p>
+ */
String value() default "";
/**
--
To stop receiving notification emails like this one, please contact
[email protected].
