You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2018/07/17 20:34:36 UTC
[juneau] branch master updated: Javadocs (mostly)
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 9e3fd80 Javadocs (mostly)
9e3fd80 is described below
commit 9e3fd809b8af613aaf0a5b2ab7d67a372d08f69d
Author: JamesBognar <ja...@apache.org>
AuthorDate: Tue Jul 17 16:34:21 2018 -0400
Javadocs (mostly)
---
.../.settings/org.eclipse.jdt.core.prefs | 2 +-
.../main/java/org/apache/juneau/BeanSession.java | 7 +
.../org/apache/juneau/http/annotation/Body.java | 175 +++++++++++++++------
.../org/apache/juneau/http/annotation/Contact.java | 6 +-
.../juneau/http/annotation/ExternalDocs.java | 35 ++++-
.../apache/juneau/http/annotation/FormData.java | 6 +-
.../apache/juneau/http/annotation/HasFormData.java | 13 +-
.../apache/juneau/http/annotation/HasQuery.java | 14 +-
.../org/apache/juneau/http/annotation/Header.java | 8 +-
.../org/apache/juneau/http/annotation/Items.java | 58 ++++++-
.../org/apache/juneau/http/annotation/License.java | 37 ++++-
.../org/apache/juneau/http/annotation/Path.java | 8 +-
.../juneau/http/annotation/PathRemainder.java | 14 +-
.../org/apache/juneau/http/annotation/Query.java | 6 +-
.../apache/juneau/http/annotation/Response.java | 15 +-
.../juneau/http/annotation/ResponseHeader.java | 12 +-
.../juneau/http/annotation/ResponseStatus.java | 12 +-
.../juneau/http/annotation/ResponseStatuses.java | 9 ++
.../apache/juneau/http/annotation/Responses.java | 8 +
.../org/apache/juneau/http/annotation/Schema.java | 43 ++++-
.../apache/juneau/http/annotation/SubItems.java | 14 +-
.../org/apache/juneau/http/annotation/Tag.java | 73 +++++----
.../apache/juneau/httppart/OpenApiPartParser.java | 57 ++++++-
.../juneau/httppart/OpenApiPartSerializer.java | 124 ++++++++++++++-
.../java/org/apache/juneau/transform/PojoSwap.java | 5 +-
juneau-doc/src/main/javadoc/overview.html | 54 +------
.../org/apache/juneau/rest/client/RestCall.java | 4 +-
.../apache/juneau/rest/BasicRestInfoProvider.java | 4 +-
.../juneau/rest/BasicRestInfoProviderTest.java | 4 +-
29 files changed, 625 insertions(+), 202 deletions(-)
diff --git a/juneau-core/juneau-marshall/.settings/org.eclipse.jdt.core.prefs b/juneau-core/juneau-marshall/.settings/org.eclipse.jdt.core.prefs
index f22162a..1e4c505 100644
--- a/juneau-core/juneau-marshall/.settings/org.eclipse.jdt.core.prefs
+++ b/juneau-core/juneau-marshall/.settings/org.eclipse.jdt.core.prefs
@@ -110,7 +110,7 @@ org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionExemptExcepti
org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionIncludeDocCommentReference=enabled
org.eclipse.jdt.core.compiler.problem.unusedDeclaredThrownExceptionWhenOverriding=disabled
org.eclipse.jdt.core.compiler.problem.unusedExceptionParameter=ignore
-org.eclipse.jdt.core.compiler.problem.unusedImport=info
+org.eclipse.jdt.core.compiler.problem.unusedImport=warning
org.eclipse.jdt.core.compiler.problem.unusedLabel=warning
org.eclipse.jdt.core.compiler.problem.unusedLocal=warning
org.eclipse.jdt.core.compiler.problem.unusedObjectAllocation=warning
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSession.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSession.java
index eb51268..dab7d57 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSession.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/BeanSession.java
@@ -475,6 +475,13 @@ public class BeanSession extends Session {
return (T)Character.valueOf(s.charAt(0));
}
+ if (to.isByteArray()) {
+ if (from.isInputStream())
+ return (T)IOUtils.readBytes((InputStream)value, 1024);
+ if (from.isReader())
+ return (T)IOUtils.read((Reader)value).getBytes();
+ }
+
// Handle setting of array properties
if (to.isArray()) {
if (from.isCollection())
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 fa2b005..f1aaa2d 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,8 +34,8 @@ import org.apache.juneau.serializer.*;
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Java method arguments of client-side REST interface proxies.
- * <li>Java method arguments of server-side REST Java methods and/or their class types.
+ * <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.
* </ul>
*
* <h5 class='topic'>Server-side REST</h5>
@@ -43,24 +43,15 @@ import org.apache.juneau.serializer.*;
* <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.
*
- * <p>
- * This annotation can be applied to the following:
- * <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='section'>Examples:</h5>
* <p class='bcode w800'>
* <jc>// Used on parameter</jc>
- * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>,path=<js>"/pets"</js>)
* <jk>public void</jk> addPet(<ja>@Body</ja> Pet pet) {...}
* </p>
* <p class='bcode w800'>
* <jc>// Used on class</jc>
- * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>,path=<js>"/pets"</js>)
* <jk>public void</jk> addPet(Pet pet) {...}
*
* <ja>@Body</ja>
@@ -70,34 +61,84 @@ import org.apache.juneau.serializer.*;
* <p>
* This is functionally equivalent to the following code...
* <p class='bcode w800'>
- * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>,path=<js>"/pets"</js>)
* <jk>public void</jk> addPet(RestRequest req) {
* Pet pet = req.getBody().asType(Pet.<jk>class</jk>);
* ...
* }
* </p>
*
- * <h5 class='section'>Notes:</h5>
- * <ul class='spaced-list'>
+ * <p>
+ * Any of the following types can be used for the parameter or POJO class (matched in the specified order):
+ * <ol class='spaced-list'>
* <li>
- * Swagger values are coalesced from multiple sources in the following order of precedence:
- * <ol>
- * <li><ja>@Body</ja> annotation on parameter.
- * <li><ja>@Body</ja> annotation on parameter class.
- * <li><ja>@Body</ja> annotation on parent classes and interfaces.
- * <li><ja>@MethodSwagger(value)</ja> annotation.
- * <li>Localized resource bundle property <js>"[method-name].produces"</js>.
- * <li><ja>@ResourceSwagger(value)</ja> annotation.
- * <li>Localized classpath resource file <js>"[enclosing-class].[simple-class-name]_[locale].json"</js> (if it's an inner or member class).
- * <li>Default classpath resource file <js>"[enclosing-class].[simple-class-name].json"</js> (if it's an inner or member class).
- * <li>Localized classpath resource file <js>"[simple-class-name]_[locale].json"</js>.
- * <li>Default classpath resource file <js>"[simple-class-name].json"</js>.
- * </ol>
- * </ul>
+ * {@link Reader}
+ * <br><ja>@Body</ja> annotation is optional.
+ * <br><code>Content-Type</code> is ignored.
+ * <li>
+ * {@link InputStream}
+ * <br><ja>@Body</ja> annotation is optional.
+ * <br><code>Content-Type</code> is ignored.
+ * <li>
+ * Any <a class='doclink' href='../../../../../overview-summary.html#juneau-marshall.PojoCategories'>Parsable POJO</a> type.
+ * <br><code>Content-Type</code> is required to identify correct parser.
+ * <li>
+ * Objects convertible from {@link 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 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 data types inferred from Swagger schema annotations using the registered {@link OpenApiPartParser}.
+ * <br>
+ * <code>Content-Type</code> must not be present or match an existing parser so that it's not parsed as a POJO.
+ * </ol>
+ *
+ * <p>
+ * Also used to populate the auto-generated Swagger documentation.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>,path=<js>"/pets"</js>)
+ * <jk>public void</jk> addPet(Pet pet) {...}
+ *
+ * <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>
+ * )
+ * <jk>public class</jk> Pet {...}
+ * </p>
+ *
+ * <p>
+ * Swagger documentation values are coalesced from multiple sources in the following order of precedence:
+ * <ol>
+ * <li><ja>@Body</ja> annotation on parameter.
+ * <li><ja>@Body</ja> annotation on parameter class.
+ * <li><ja>@Body</ja> annotation on parent classes and interfaces.
+ * <li><ja>@MethodSwagger(value)</ja> annotation.
+ * <li>Localized resource bundle property <js>"[method-name].produces"</js>.
+ * <li><ja>@ResourceSwagger(value)</ja> annotation.
+ * <li>Localized classpath resource file <js>"[enclosing-class].[simple-class-name]_[locale].json"</js> (if it's an inner or member class).
+ * <li>Default classpath resource file <js>"[enclosing-class].[simple-class-name].json"</js> (if it's an inner or member class).
+ * <li>Localized classpath resource file <js>"[simple-class-name]_[locale].json"</js>.
+ * <li>Default classpath resource file <js>"[simple-class-name].json"</js>.
+ * </ol>
*
* <h5 class='section'>See Also:</h5>
* <ul>
* <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Body">Overview > juneau-rest-server > @Body</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#parameterObject">Swagger Specification > Parameter Object</a>
* </ul>
*
@@ -105,13 +146,45 @@ import org.apache.juneau.serializer.*;
*
* Annotation applied to Java method arguments of interface proxies to denote that they are the HTTP body of the request.
*
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode'>
+ * <jc>// Used on parameter</jc>
+ * <ja>@Remoteable</ja>(path=<js>"/petstore"</js>)
+ * <jk>public interface</jk> PetStore {
+ *
+ * <ja>@RemoteMethod</ja>(path=<js>"/pets"</js>)
+ * String addPet(<ja>@Body</ja> Pet pet);
+ * }
+ * </p>
+ * <p class='bcode'>
+ * <jc>// Used on class</jc>
+ * <ja>@Remoteable</ja>(path=<js>"/petstore"</js>)
+ * <jk>public interface</jk> PetStore {
+ *
+ * <ja>@RemoteMethod</ja>(path=<js>"/pets"</js>)
+ * String addPet(Pet pet);
+ * }
+ *
+ * <ja>@Body</ja>
+ * <jk>public class</jk> Pet {...}
+ * </p>
+ *
+ * <p>
+ * The annotation can also be applied to a bean property field or getter when the argument is annotated with
+ * {@link RequestBean @RequestBean}:
+ *
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
* <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>)
* <jk>public interface</jk> MyProxy {
*
* <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>)
- * String myProxyMethod(<ja>@Body</ja> MyPojo pojo);
+ * String myProxyMethod(<ja>@RequestBean</ja> MyRequestBean bean);
+ * }
+ *
+ * <jk>public interface</jk> MyRequestBean {
+ * <ja>@Body</ja>
+ * MyPojo getMyPojo();
* }
* </p>
*
@@ -132,27 +205,37 @@ import org.apache.juneau.serializer.*;
* </ul>
*
* <p>
- * The annotation can also be applied to a bean property field or getter when the argument is annotated with
- * {@link RequestBean @RequestBean}:
+ * OpenAPI schema based serialization can be used by specifying a value for the {@link #serializer()} annotation.
*
- * <h5 class='section'>Example:</h5>
* <p class='bcode'>
- * <ja>@Remoteable</ja>(path=<js>"/myproxy"</js>)
- * <jk>public interface</jk> MyProxy {
- *
- * <ja>@RemoteMethod</ja>(path=<js>"/mymethod"</js>)
- * String myProxyMethod(<ja>@RequestBean</ja> MyRequestBean bean);
- * }
- *
- * <jk>public interface</jk> MyRequestBean {
- * <ja>@Body</ja>
- * MyPojo getMyPojo();
- * }
+ * <ja>@RemoteMethod</ja>(path=<js>"/comma-delimited-pipe-delimited-ints"</js>)
+ * String addCommaDelimitedPipeDelimitedInts(
+ * <ja>@Body</ja>(
+ * serializer=OpenApiPartSerializer.<jk>class</jk>,
+ * schema=<ja>@Schema</ja>(
+ * type=<js>"array"</js>,
+ * collectionFormat=<js>"pipes"</js>,
+ * items=<ja>@Items</ja>(
+ * type=<js>"array"</js>
+ * items=<ja>@SubItems</ja>(
+ * type=<js>"int32"</js>,
+ * <jc>// Auto-validates on client side!</jc>
+ * minimum=<js>"0"</js>,
+ * maximum=<js>"64"</js>
+ * )
+ * )
+ * )
+ * )
+ * <jk>int</jk>[][] input
+ * );
* </p>
*
+ * <p>
+ * When using OpenAPI serialization, the argument can be any data type specified in {@link OpenApiPartSerializer}.
+ *
* <h5 class='section'>See Also:</h5>
* <ul class='doctree'>
- * <li class='link'><a class='doclink' href='../../../../overview-summary.html#juneau-rest-client.3rdPartyProxies.Body'>Overview > juneau-rest-client > Interface Proxies Against 3rd-party REST Interfaces > Body</a>
+ * <li class='link'><a class='doclink' href='../../../../../overview-summary.html#juneau-rest-client.3rdPartyProxies.Body'>Overview > juneau-rest-client > Interface Proxies Against 3rd-party REST Interfaces > Body</a>
* </ul>
*/
@Documented
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Contact.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Contact.java
index e0b1b0f..b367a2f 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Contact.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Contact.java
@@ -17,14 +17,15 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
-
/**
* Swagger contact annotation.
*
* <p>
* The contact information for the exposed API.
*
+ * <p>
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ *
* <h5 class='section'>Examples:</h5>
* <p class='bcode w800'>
* <jc>// Normal</jc>
@@ -54,6 +55,7 @@ import org.apache.juneau.json.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#contactObject">Swagger Specification > Contact Object</a>
* </ul>
*/
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ExternalDocs.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ExternalDocs.java
index 4e3e511..74f1b15 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ExternalDocs.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ExternalDocs.java
@@ -12,13 +12,42 @@
// ***************************************************************************************************************************
package org.apache.juneau.http.annotation;
-import org.apache.juneau.json.*;
-
/**
- * TODO
+ * Swagger external documentation annotation.
+ *
+ * <p>
+ * Allows referencing an external resource for extended documentation.
+ *
+ * <p>
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * externalDocs=<ja>@ExternalDocs</ja>(
+ * description=<js>"Apache Juneau"</js>,
+ * url=<js>"http://juneau.apache.org"</js>
+ * )
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * contact=<ja>@ExternalDocs</ja>({
+ * <js>"description:'Apache Juneau',"</js>,
+ * <js>"url:'http://juneau.apache.org'"</js>,
+ * })
+ * )
+ * )
+ * </p>
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#externalDocumentationObject">Swagger Specification > External Documentation Object</a>
* </ul>
*/
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 ac9b4fe..e6e0efb 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
@@ -20,7 +20,6 @@ import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.remoteable.*;
import org.apache.juneau.urlencoding.*;
@@ -33,8 +32,8 @@ import org.apache.juneau.urlencoding.*;
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Java method arguments of client-side REST interface proxies.
- * <li>Java method arguments of server-side REST Java methods and/or their class types.
+ * <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.
* </ul>
*
* <h5 class='topic'>Server-side REST</h5>
@@ -76,6 +75,7 @@ import org.apache.juneau.urlencoding.*;
* <h5 class='section'>See Also:</h5>
* <ul>
* <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.FormData">Overview > juneau-rest-server > @FormData</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#parameterObject">Swagger Specification > Parameter Object</a>
* </ul>
*
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 7cbd467..19f3047 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
@@ -18,8 +18,15 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Annotation that can be applied to a parameter of a <ja>@RestMethod</ja> annotated method to identify whether or not
- * the request has the specified multipart form POST parameter.
+ * REST has-form-data annotation.
+ *
+ * Identifies whether or not an HTTP request has the specified multipart form POST parameter.
+ *
+ * <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.
+ * </ul>
*
* <p>
* Note that this can be used to detect the existence of a parameter when it's not set to a particular value.
@@ -84,7 +91,7 @@ import java.lang.annotation.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
- * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.FormData">Overview > juneau-rest-server > @FormData</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.HasFormData">Overview > juneau-rest-server > @HasFormData</a>
* </ul>
*/
@Documented
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 d6e2341..2ec9825 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
@@ -18,6 +18,18 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
+ * REST has-query-parameter annotation.
+ *
+ * <p>
+ * Identifies whether or not an HTTP request has the specified query parameter.
+ *
+ * <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.
+ * </ul>
+ *
+ * <p>
* Identical to {@link HasFormData @HasFormData}, but only checks the existing of the parameter in the URL string, not
* URL-encoded form posts.
*
@@ -47,7 +59,7 @@ import java.lang.annotation.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
- * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Query">Overview > juneau-rest-server > @Query</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.HasQuery">Overview > juneau-rest-server > @HasQuery</a>
* </ul>
*/
@Documented
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 ffd22a7..1a6621b 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
@@ -20,12 +20,11 @@ import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.remoteable.*;
import org.apache.juneau.urlencoding.*;
/**
- * REST request body annotation.
+ * REST request header annotation.
*
* <p>
* Identifies a POJO to be used as the header of an HTTP request.
@@ -33,8 +32,8 @@ import org.apache.juneau.urlencoding.*;
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Java method arguments of client-side REST interface proxies.
- * <li>Java method arguments of server-side REST Java methods and/or their class types.
+ * <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.
* </ul>
*
* <h5 class='topic'>Server-side REST</h5>
@@ -63,6 +62,7 @@ import org.apache.juneau.urlencoding.*;
* <h5 class='section'>See Also:</h5>
* <ul>
* <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Header">Overview > juneau-rest-server > @Header</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#parameterObject">Swagger Specification > Parameter Object</a>
* </ul>
*
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Items.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Items.java
index d25dcfc..2ad69c9 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Items.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Items.java
@@ -17,19 +17,65 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
+import org.apache.juneau.httppart.*;
/**
- * Swagger schema annotation.
+ * Swagger items annotation.
*
* <p>
- * The Schema Object allows the definition of input and output data types.
- * These types can be objects, but also primitives and arrays.
- * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
- * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+ * A limited subset of JSON-Schema's items object.
+ *
+ * <p>
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiPartSerializer} and parsed through {@link OpenApiPartParser}.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Items have a specific set of enumerated string values</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</js>,
+ * collectionFormat=<js>"csv"</js>,
+ * items=<ja>@Items</ja>(
+ * type=<js>"string"</js>,
+ * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>,
+ * _default=<js>"AVAILABLE"</js>
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Same but defined free-form</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</js>,
+ * collectionFormat=<js>"csv"</js>,
+ * items=<ja>@Items</ja>({
+ * <js>"type:'string',"</js>,
+ * <js>"enum:'AVAILABLE,PENDING,SOLD',"</js>,
+ * <js>"default:'AVAILABLE'"</js>
+ * })
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// An array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</js>,
+ * collectionFormat=<js>"csv"</js>,
+ * items=<ja>@Items</ja>(
+ * type=<js>"array"</js>,
+ * items=<ja>@SubItems</ja>(
+ * type=<js>"integer"</js>,
+ * minimum=<js>"0"</js>,
+ * maximum=<js>"63"</js>
+ * )
+ * )
+ * )
+ * </p>
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#itemsObject">Swagger Specification > Items Object</a>
* </ul>
*/
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/License.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/License.java
index e94befb..db0aada 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/License.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/License.java
@@ -17,19 +17,42 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
-
/**
- * Swagger schema annotation.
+ * Swagger license annotation.
+ *
+ * <p>
+ * License information for the exposed API.
*
* <p>
- * The Schema Object allows the definition of input and output data types.
- * These types can be objects, but also primitives and arrays.
- * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
- * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * license=<ja>@License</ja>(
+ * name=<js>"Apache 2.0"</js>,
+ * url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
+ * )
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * license=<ja>@License</ja>({
+ * <js>"name:'Apache 2.0',"</js>,
+ * <js>"url:'http://www.apache.org/licenses/LICENSE-2.0.html'"</js>
+ * })
+ * )
+ * )
+ * </p>
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#licenseObject">Swagger Specification > License Object</a>
* </ul>
*/
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 348e3ad..6f1d99b 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
@@ -19,7 +19,6 @@ import java.lang.annotation.*;
import org.apache.juneau.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.remoteable.*;
import org.apache.juneau.urlencoding.*;
@@ -32,8 +31,8 @@ import org.apache.juneau.urlencoding.*;
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Java method arguments of client-side REST interface proxies.
- * <li>Java method arguments of server-side REST Java methods and/or their class types.
+ * <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.
* </ul>
*
* <h5 class='topic'>Server-side REST</h5>
@@ -52,7 +51,8 @@ import org.apache.juneau.urlencoding.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
- * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.MethodParameters">Overview > juneau-rest-server > Method Parameters</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Path">Overview > juneau-rest-server > @Path</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#parameterObject">Swagger Specification > Parameter Object</a>
* </ul>
*
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/PathRemainder.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/PathRemainder.java
index 445dfe5..e7fcd90 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/PathRemainder.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/PathRemainder.java
@@ -18,8 +18,16 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Annotation that can be applied to a parameter of a <ja>@RestMethod</ja>-annotated method to identify it as the URL
- * parameter remainder after a path pattern match.
+ * REST request path remainder annotation.
+ *
+ * <p>
+ * Identifies a parameter as the URL path remainder after a path pattern match.
+ *
+ * <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.
+ * </ul>
*
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
@@ -41,7 +49,7 @@ import java.lang.annotation.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
- * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.MethodParameters">Overview > juneau-rest-server > Method Parameters</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.PathRemainder">Overview > juneau-rest-server > @PathRemainder</a>
* </ul>
*/
@Documented
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 d976ec8..cb14db2 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
@@ -20,7 +20,6 @@ import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.remoteable.*;
import org.apache.juneau.urlencoding.*;
@@ -33,8 +32,8 @@ import org.apache.juneau.urlencoding.*;
* <p>
* Can be used in the following locations:
* <ul>
- * <li>Java method arguments of client-side REST interface proxies.
- * <li>Java method arguments of server-side REST Java methods and/or their class types.
+ * <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.
* </ul>
*
* <h5 class='topic'>Server-side REST</h5>
@@ -72,6 +71,7 @@ import org.apache.juneau.urlencoding.*;
* <h5 class='section'>See Also:</h5>
* <ul>
* <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Query">Overview > juneau-rest-server > @Query</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#parameterObject">Swagger Specification > Parameter Object</a>
* </ul>
*
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 afa9fb2..4136bfa 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
@@ -18,10 +18,19 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
/**
- * Annotation that can be applied to exceptions and return types on server-side REST methods that identify the HTTP status they trigger and a description about the exception.
+ * REST response annotation.
+ *
+ * Identifies the HTTP status code and description about an HTTP response.
+ *
+ * <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.
+ * <li>Exception classes thrown from <ja>@RestMethod</ja>-annotated REST Java methods.
+ * </ul>
*
* <p>
* When applied to exception classes, this annotation defines Swagger information on non-200 return types.
@@ -96,6 +105,8 @@ import org.apache.juneau.json.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Response">Overview > juneau-rest-server > @Response</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#responseObject">Swagger Specification > Response Object</a>
* </ul>
*/
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 4e14d80..dedde14 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
@@ -18,13 +18,21 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.httppart.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.utils.*;
/**
+ * REST response header annotation.
+ *
+ * <p>
* Annotation that can be applied to parameters and types to denote them as an HTTP response headers.
*
* <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.
+ * </ul>
+ *
+ * <p>
* This annotation can only be applied to subclasses of type {@link Value}.
*
* <p>
@@ -62,6 +70,8 @@ import org.apache.juneau.utils.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.ResponseHeader">Overview > juneau-rest-server > @ResponseHeader</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#headerObject">Swagger Specification > Header Object</a>
* </ul>
*/
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 395d1b9..a0603fd 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
@@ -16,13 +16,21 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.utils.*;
/**
+ * REST response status annotation.
+ *
+ * <p>
* Annotation that can be applied to parameters and types to denote them as an HTTP response status on server-side REST method parameters.
*
* <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.
+ * </ul>
+ *
+ * <p>
* This can only be applied to parameters and subclasses of the {@link Value} class with an {@link Integer} type.
* <br>The {@link Value} object is mean to be a place-holder for the set value.
*
@@ -95,6 +103,8 @@ import org.apache.juneau.utils.*;
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.ResponseStatus">Overview > juneau-rest-server > @ResponseStatus</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#responseObject">Swagger Specification > Response Object</a>
* </ul>
*/
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatuses.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatuses.java
index bdbcd9b..ad5c8cd 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatuses.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/ResponseStatuses.java
@@ -18,11 +18,20 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
+ * REST response statuses annotation.
+ *
+ * <p>
* Used to associate multiple {@link ResponseStatus @ResponseStatus} annotations to the same parameter or class.
*
* <p>
* Since Juneau currently prereq's Java 1.7, we cannot take advantage of annotation duplication support in Java 8.
* <br>This annotation overcomes that limitation.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.ResponseStatuses">Overview > juneau-rest-server > @ResponseStatuses</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Responses.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Responses.java
index 74611b2..78896ed 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Responses.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Responses.java
@@ -18,11 +18,19 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
+ * REST responses annotation.
+ *
* Used to associate multiple {@link Response @Response} annotations to the same parameter or class.
*
* <p>
* Since Juneau currently prereq's Java 1.7, we cannot take advantage of annotation duplication support in Java 8.
* <br>This annotation overcomes that limitation.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.Responses">Overview > juneau-rest-server > @Responses</a>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Schema.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Schema.java
index 6d470e1..49432be 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Schema.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Schema.java
@@ -17,7 +17,7 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
+import org.apache.juneau.httppart.*;
/**
* Swagger schema annotation.
@@ -28,8 +28,49 @@ import org.apache.juneau.json.*;
* This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
* On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
*
+ * <p>
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiPartSerializer} and parsed through {@link OpenApiPartParser}.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// A response object thats a hex-encoded string</jc>
+ * <ja>@Response</ja>(
+ * schema=<ja>@Schema</ja>(
+ * type=<js>"string"</js>,
+ * format=<js>"binary"</js>
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Response</ja>(
+ * schema=<ja>@Schema</ja>({
+ * <js>"type:'string',"</js>,
+ * <js>"format:'binary'"</js>
+ * })
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// A request body consisting of an array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive)</jc>
+</jc>
+ * <ja>@Body</ja>(
+ * schema=<ja>@Schema</ja>(
+ * items=<ja>@Items</ja>(
+ * type=<js>"array"</js>,
+ * items=<ja>@SubItems</ja>(
+ * type=<js>"integer"</js>,
+ * minimum=<js>"0"</js>,
+ * maximum=<js>"63"</js>
+ * )
+ * )
+ * )
+ * )
+ * </p>
+ *
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#schemaObject">Swagger Specification > Schema Object</a>
* </ul>
*/
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/SubItems.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/SubItems.java
index d31e47a..7b19eb4 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/SubItems.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/SubItems.java
@@ -17,19 +17,19 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
-
/**
- * Swagger schema annotation.
+ * Swagger items annotation.
+ *
+ * <p>
+ * This class is essentially identical to {@link Items} except it's used for defining items of items.
*
* <p>
- * The Schema Object allows the definition of input and output data types.
- * These types can be objects, but also primitives and arrays.
- * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
- * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+ * Since annotations cannot be nested, we're forced to create a separate annotation for it.
+ * <br>If you want to nest items further, you have to define them free-form using {@link #items()} as free-form JSON.
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#itemsObject">Swagger Specification > Items Object</a>
* </ul>
*/
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Tag.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Tag.java
index 26d3005..2bb04fe 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Tag.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Tag.java
@@ -17,19 +17,47 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
-import org.apache.juneau.json.*;
-
/**
- * Swagger schema annotation.
+ * Swagger tag annotation.
+ *
+ * <p>
+ * Allows adding meta data to a single tag that is used by the <a class='doclink' href='https://swagger.io/specification/v2/#operationObject'>Operation Object</a>.
+ * It is not mandatory to have a Tag Object per tag used there.
*
* <p>
- * The Schema Object allows the definition of input and output data types.
- * These types can be objects, but also primitives and arrays.
- * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
- * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
+ * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// A response object thats a hex-encoded string</jc>
+ * <ja>@RestResource</ja>(
+ * swagger={
+ * tags={
+ * <ja>@Tag</ja>(
+ * name=<js>"utility"</js>,
+ * description=<js>"Utility methods"</js>
+ * )
+ * }
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestResource</ja>(
+ * swagger={
+ * tags={
+ * <ja>@Tag</ja>({
+ * <js>"name:'utility',"</js>,
+ * <js>"description:'Utility methods'"</js>
+ * })
+ * }
+ * }
+ * )
+ * </p>
*
* <h5 class='section'>See Also:</h5>
* <ul>
+ * <li class='link'><a class="doclink" href="../../../../../overview-summary.html#juneau-rest-server.OptionsPages">Overview > juneau-rest-server > OPTIONS pages and Swagger</a>
* <li class='link'><a class="doclink" href="https://swagger.io/specification/v2/#tagObject">Swagger Specification > Tag Object</a>
* </ul>
*/
@@ -51,35 +79,6 @@ public @interface Tag {
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 "";
-
- /**
* <mk>description</mk> field of the Swagger <a class="doclink" href="https://swagger.io/specification/v2/#tagObject">Tag</a> object.
*
* <h5 class='section'>Notes:</h5>
@@ -195,5 +194,5 @@ public @interface Tag {
* Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
* </ul>
*/
- String[] api() default {};
+ String[] value() default {};
}
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartParser.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartParser.java
index 7510058..2b61c73 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartParser.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartParser.java
@@ -13,14 +13,19 @@
package org.apache.juneau.httppart;
import java.io.*;
+import java.nio.charset.*;
import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.parser.*;
+import org.apache.juneau.transform.*;
/**
* OpenAPI part parser.
*
+ * <p>
+ * TODO
+ *
* <table class='styled'>
* <tr><th>Type</th><th>Format</th><th>Valid parameter types</th></tr>
* <tr>
@@ -37,7 +42,14 @@ import org.apache.juneau.parser.*;
* <li>{@link Reader} - Returns a {@link InputStreamReader} wrapped around a {@link ByteArrayInputStream}.
* <li>{@link String} - Constructed using {@link String#String(byte[])}.
* <li>{@link Object} - Returns the default <code><jk>byte</jk>[]</code>.
- * <li>Any POJO transformable from a <code><jk>byte</jk>[]</code> (via constructors, static create methods, or toX() instance methods).
+ * <li>Any POJO transformable from a <code><jk>byte</jk>[]</code> via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> T(<jk>byte</jk>[] in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>create</jsm>(<jk>byte</jk>[] in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromBytes</jsm>(<jk>byte</jk>[] in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromFoo</jsm>(<jk>byte</jk>[] in) {...}</code> (any method name starting with "from")
+ * </ul>
+ * <li>Any POJO transformable from a <code><jk>byte</jk>[]</code> via a {@link PojoSwap}:
* </ul>
* </td>
* </tr>
@@ -54,7 +66,14 @@ import org.apache.juneau.parser.*;
* <li>{@link GregorianCalendar}
* <li>{@link String} - Converted using {@link Calendar#toString()}.
* <li>{@link Object} - Returns the default {@link Calendar}.
- * <li>Any POJO transformable from a {@link Calendar} (via constructors, static create methods, or toX() instance methods).
+ * <li>Any POJO transformable from a {@link Calendar} via the following methods.
+ * <ul>
+ * <li><code><jk>public</jk> T(Calendar in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>create</jsm>(Calendar in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromCalendar</jsm>(Calendar in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromFoo</jsm>(Calendar in) {...}</code> (any method name starting with "from")
+ * </ul>
+ * <li>Any POJO transformable from a {@link Calendar} via a {@link PojoSwap}:
* </ul>
* </td>
* </tr>
@@ -63,7 +82,7 @@ import org.apache.juneau.parser.*;
* <td><code>uon</code></td>
* <td>
* <ul>
- * <li>Any <a href='../../../../overview-summary#juneau-marshall.PojoCategories'>parsable POJO</a>.
+ * <li>Any <a class='doclink' href='../../../../overview-summary.html#juneau-marshall.PojoCategories'>Parsable POJO</a> type.
* </ul>
* </td>
* </tr>
@@ -74,7 +93,19 @@ import org.apache.juneau.parser.*;
* <ul>
* <li>{@link String} (default)
* <li>{@link Object} - Returns the default {@link String}.
- * <li>Any POJO transformable from a {@link String} (via constructors, static create methods, or toX() instance methods).
+ * <li>Any POJO transformable from a {@link String} via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> T(String in) {...}</code> (e.g. {@link java.lang.Integer}, {@link java.lang.Boolean})
+ * <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>fromValue</jsm>(String in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>valueOf</jsm>(String in) {...}</code> (e.g. enums)
+ * <li><code><jk>public static</jk> T <jsm>parse</jsm>(String in) {...}</code> (e.g. {@link java.util.logging.Level})
+ * <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> (e.g. {@link java.lang.Class}, {@link Charset})
+ * <li><code><jk>public static</jk> T <jsm>forString</jsm>(String in) {...}</code>
+ * </ul>
+ * <li>Any POJO transformable from a {@link String} via a {@link PojoSwap}:
* </ul>
* </td>
* </tr>
@@ -89,7 +120,14 @@ import org.apache.juneau.parser.*;
* <li><jk>boolean</code>
* <li>{@link String}
* <li>{@link Object} - Returns the default {@link Boolean}.
- * <li>Any POJO transformable from a {@link Boolean} (via constructors, static create methods, or toX() instance methods).
+ * <li>Any POJO transformable from a {@link Boolean} via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> T(Boolean in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>create</jsm>(Boolean in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromBoolean</jsm>(Boolean in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromFoo</jsm>(Boolean in) {...}</code> (any method name starting with "from")
+ * </ul>
+ * <li>Any POJO transformable from a {@link Boolean} via a {@link PojoSwap}:
* </ul>
* </td>
* </tr>
@@ -100,8 +138,15 @@ import org.apache.juneau.parser.*;
* </td>
* <td>
* <ul>
- * <li>Arrays or Collections of anything on this list.
+ * <li>Arrays or Collections of any defaults on this list.
* <li>Any POJO transformable from arrays of the default types (e.g. <code>Integer[]</code>, <code>Boolean[][]</code>, etc...).
+ * <br>For example:
+ * <ul>
+ * <li><code><jk>public</jk> T(Boolean[][] in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>create</jsm>(Boolean[][] in) {...}</code>
+ * <li><code><jk>public static</jk> T <jsm>fromFoo</jsm>(Boolean[][] in) {...}</code> (any method name starting with "from")
+ * </ul>
+ * <li>Any POJO transformable from arrays of the default types via a {@link PojoSwap}:
* </ul>
* </td>
* </tr>
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartSerializer.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartSerializer.java
index ba5ae38..11e4406 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartSerializer.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/httppart/OpenApiPartSerializer.java
@@ -12,15 +12,135 @@
// ***************************************************************************************************************************
package org.apache.juneau.httppart;
+import java.io.*;
+import java.util.*;
+
import org.apache.juneau.*;
import org.apache.juneau.serializer.*;
+import org.apache.juneau.transform.*;
/**
* Serializes POJOs to values suitable for transmission as HTTP headers, query/form-data parameters, and path variables.
*
* <p>
- * This serializer uses UON notation for all parts by default. This allows for arbitrary POJOs to be losslessly
- * serialized as any of the specified HTTP types.
+ * TODO
+ *
+ * <table class='styled'>
+ * <tr><th>Type</th><th>Format</th><th>Valid parameter types</th></tr>
+ * <tr>
+ * <td ><code>string</code></td>
+ * <td>
+ * <code>byte</code>
+ * <br><code>binary</code>
+ * <br><code>binary-spaced</br>
+ * </td>
+ * <td>
+ * <ul>
+ * <li><code><jk>byte</jk>[]</code> (default)
+ * <li>{@link InputStream}
+ * <li>{@link Reader} - Read into String and then converted using {@link String#getBytes()}.
+ * <li>{@link Object} - Converted to String and then converted using {@link String#getBytes()}.
+ * <li>Any POJO transformable to a <code><jk>byte</jk>[]</code> via the following methods:
+ * <ul>
+ * <li><code><jk>public byte</jk>[] toBytes() {...}</code>
+ * <li><code><jk>public byte</jk>[]</jk> toFoo() {...}</code> (any method name starting with "to")
+ * </ul>
+ * <li>Any POJO transformable to a <code><jk>byte</jk>[]</code> via a {@link PojoSwap}.
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>string</code></td>
+ * <td>
+ * <code>date</code>
+ * <code>date-time</code>
+ * </td>
+ * <td>
+ * <ul>
+ * <li>{@link Calendar} (default)
+ * <li>{@link Date}
+ * <li>Any POJO transformable to a {@link Calendar} via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> Calendar toCalendar() {...}</code>
+ * <li><code><jk>public</jk> Calendar toFoo() {...}</code> (any method name starting with "to")
+ * </ul>
+ * <li>Any POJO transformable to a {@link Calendar} via a {@link PojoSwap}.
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>string</code></td>
+ * <td><code>uon</code></td>
+ * <td>
+ * <ul>
+ * <li>Any <a class='doclink' href='../../../../overview-summary.html#juneau-marshall.PojoCategories'>Serializable POJO</a> type.
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>string</code></td>
+ * <td>none specified</td>
+ * <td>
+ * <ul>
+ * <li>{@link String} (default)
+ * <li>Any POJO transformable to a {@link String} via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> String toString() {...}</code>
+ * </ul>
+ * <li>Any POJO transformable to a {@link String} via a {@link PojoSwap}.
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>boolean</code></td>
+ * <td>
+ *
+ * </td>
+ * <td>
+ * <ul>
+ * <li>{@link Boolean} (default)
+ * <li><jk>boolean</jk>
+ * <li>{@link String} - Converted to a {@link Boolean}.
+ * <li>Any POJO transformable to a {@link Boolean} via the following methods:
+ * <ul>
+ * <li><code><jk>public</jk> Boolean toBoolean() {...}</code>
+ * <li><code><jk>public</jk> Boolean toFoo() {...}</code> (any method name starting with "to")
+ * </ul>
+ * <li>Any POJO transformable to a {@link Boolean} via a {@link PojoSwap}.
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>array</code></td>
+ * <td>
+ *
+ * </td>
+ * <td>
+ * <ul>
+ * <li>Arrays or Collections of any defaults on this list.
+ * <li>Any POJO transformable to arrays of the default types (e.g. <code>Integer[]</code>, <code>Boolean[][]</code>, etc...).
+ * <br>For example:
+ * <ul>
+ * <li><code><jk>public</jk> Boolean[][] toFoo() {...}</code> (any method name starting with "to")
+ * </ul>
+ * <li>Any POJO transformable to arrays of the default types via a {@link PojoSwap}
+ * </ul>
+ * </td>
+ * </tr>
+ * <tr>
+ * <td ><code>object</code></td>
+ * <td>
+ *
+ * </td>
+ * <td>
+ * <ul>
+ * <li>Beans with properties of anything on this list.
+ * <li>Maps with string keys.
+ * <li>Any POJO transformable to a map via a {@link PojoSwap}
+ * </ul>
+ * </td>
+ * </tr>
+ * </table>
*/
public class OpenApiPartSerializer extends UonPartSerializer {
diff --git a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
index 0c9089c..b8c9266 100644
--- a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
+++ b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/transform/PojoSwap.java
@@ -64,7 +64,7 @@ import org.apache.juneau.serializer.*;
* <h5 class='topic'>Swap Class Type {@code <S>}</h5>
*
* <p>
- * The swapped object representation of an object must be an object type that the serializers can natively convert to
+ * For normal serialization, the swapped object representation of an object must be an object type that the serializers can natively convert to
* JSON (or language-specific equivalent).
* <br>The list of valid transformed types are as follows...
* <ul>
@@ -84,6 +84,9 @@ import org.apache.juneau.serializer.*;
* An array of anything on this list.
* </ul>
*
+ * <p>
+ * For OpenAPI serialization, the valid swapped types also include <code><jk>byte</jk>[]</code> and <code>Calendar</code>.
+ *
* <h5 class='topic'>Normal Class Type {@code <T>}</h5>
*
* <p>
diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html
index ee13f83..5403156 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -12826,56 +12826,6 @@
}
</p>
- <p>
- Any of the following types can be used for the parameter or POJO class (matched in the specified order):
- </p>
- <ol class='spaced-list'>
- <li>
- {@link java.util.Reader}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- {@link java.util.InputStream}
- <br><ja>@Body</ja> annotation is optional.
- <br><code>Content-Type</code> is ignored.
- <li>
- Any <a class='doclink' href='../../../../../overview-summary.html#juneau-marshall.PojoCategories'>parsable</a> POJO type.
- <br><code>Content-Type</code> is required to identify correct parser.
- <li>
- Objects convertible from {@link java.util.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>
- <br><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.util.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>
- <br><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} (including <code>String</code> itself) by having one of the following non-deprecated methods:
- <ul>
- <li><code><jk>public</jk> T(String in) {...}</code> (e.g. {@link java.lang.Integer}, {@link java.lang.Boolean})
- <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>fromValue</jsm>(String in) {...}</code>
- <li><code><jk>public static</jk> T <jsm>valueOf</jsm>(String in) {...}</code> (e.g. enums)
- <li><code><jk>public static</jk> T <jsm>parse</jsm>(String in) {...}</code> (e.g. {@link java.util.logging.Level})
- <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> (e.g. {@link java.lang.Class}, {@link java.util.Charset})
- <li><code><jk>public static</jk> T <jsm>forString</jsm>(String in) {...}</code>
- </ul>
- <br><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 data types inferred from Swagger schema annotations using the registered {@link org.apache.juneau.rest.RestContext#REST_partParser}.
- <br>
- <br><code>Content-Type</code> must not be present or match an existing parser so that it's not parsed as a POJO.
- </ol>
<h5 class='figure'>Examples:</h5>
<p class='bcode w800'>
@@ -12942,7 +12892,7 @@
<jc>// Normal</jc>
<ja>@Body</ja>(
description=<js>"Pet object to add to the store"</js>,
- required=<js>"true"</js>,
+ required=<jk>true</jk>,
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
)
</p>
@@ -12959,7 +12909,7 @@
<jc>// Localized</jc>
<ja>@Body</ja>(
description=<js>"$L{My.Localized.Description}"</js>,
- required=<js>"true"</js>,
+ required=<jk>true</jk>,
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
)
</p>
diff --git a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCall.java b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCall.java
index 7c1e145..b3ddec2 100644
--- a/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCall.java
+++ b/juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestCall.java
@@ -551,12 +551,12 @@ public final class RestCall extends BeanSession implements Closeable {
public RestCall body(Object input, HttpPartSerializer partSerializer, HttpPartSchema schema) throws RestCallException {
try {
if (partSerializer != null)
- body(partSerializer.serialize(HttpPartType.BODY, schema, input));
+ body(new StringEntity(partSerializer.serialize(HttpPartType.BODY, schema, input)));
else
body(input);
} catch (SchemaValidationException e) {
throw new RestCallException(e, "Validation error on request body.");
- } catch (SerializeException e) {
+ } catch (Exception e) {
throw new RestCallException(e, "Serialization error on request body.");
}
return this;
diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
index b38fe3a..6c0bc20 100644
--- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
+++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
@@ -833,8 +833,8 @@ public class BasicRestInfoProvider implements RestInfoProvider {
}
private ObjectMap toMap(VarResolverSession vs, Tag a, String location, Object...locationArgs) throws ParseException {
- ObjectMap om = newMap(vs, new ObjectMap(), a.api(), location, locationArgs);
- om.appendSkipEmpty("name", vs.resolve(firstNonEmpty(a.name(), a.value())));
+ ObjectMap om = newMap(vs, new ObjectMap(), a.value(), location, locationArgs);
+ om.appendSkipEmpty("name", vs.resolve(a.name()));
om.appendSkipEmpty("description", vs.resolve(joinnl(a.description())));
om.appendSkipNull("externalDocs", merge(om.getObjectMap("externalDocs"), toMap(vs, a.externalDocs(), location, locationArgs)));
return om.isEmpty() ? null : om;
diff --git a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java
index 50d93d2..527f185 100644
--- a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java
+++ b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java
@@ -392,7 +392,7 @@ public class BasicRestInfoProviderTest {
@RestResource(
swagger=@ResourceSwagger(
value="{tags:[{name:'a-name',description:'a-description',externalDocs:{description:'a-description',url:'a-url'}}]}",
- tags=@Tag(name="b-name",api=" { description:'b-description', externalDocs: { description:'b-description', url:'b-url' } } ")
+ tags=@Tag(name="b-name",value=" { description:'b-description', externalDocs: { description:'b-description', url:'b-url' } } ")
)
)
public static class C04 {}
@@ -432,7 +432,7 @@ public class BasicRestInfoProviderTest {
swagger=@ResourceSwagger(
tags={
@Tag(name="s-name",description="b-description",externalDocs=@ExternalDocs(description="b-description",url="b-url")),
- @Tag(name="s-name",api="{description:'c-description',externalDocs:{description:'c-description',url:'c-url'}}")
+ @Tag(name="s-name",value="{description:'c-description',externalDocs:{description:'c-description',url:'c-url'}}")
}
)
)