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 4d00186 Javadocs.
4d00186 is described below
commit 4d0018661f120b6c80a9aac613f6d7f9801e9beb
Author: JamesBognar <[email protected]>
AuthorDate: Sun Jun 10 17:40:35 2018 -0400
Javadocs.
---
.../apache/juneau/dto/jsonschema/JsonSchema.java | 24 +-
.../juneau/dto/jsonschema/JsonSchemaMap.java | 4 +-
.../jsonschema/JsonSchemaPropertySimpleArray.java | 4 +-
.../juneau/dto/jsonschema/JsonSchemaRef.java | 2 +-
.../org/apache/juneau/dto/jsonschema/package.html | 60 ++---
juneau-doc/src/main/javadoc/overview.html | 36 +--
.../src/main/javadoc/resources/juneau-code.css | 1 +
.../juneau/examples/rest/petstore/PetCreate.java | 2 +-
.../examples/rest/petstore/PetStoreResource.java | 14 +-
.../apache/juneau/rest/BasicRestInfoProvider.java | 14 +-
.../java/org/apache/juneau/rest/RestContext.java | 8 +-
.../org/apache/juneau/rest/RestParamDefaults.java | 8 +-
.../org/apache/juneau/rest/annotation/Body.java | 299 ++++++++++++++++-----
.../org/apache/juneau/rest/annotation/Contact.java | 116 +++++++-
.../juneau/rest/annotation/ExternalDocs.java | 80 +++++-
.../apache/juneau/rest/annotation/FormData.java | 77 +++++-
.../org/apache/juneau/rest/annotation/Header.java | 76 +++++-
.../org/apache/juneau/rest/annotation/Items.java | 99 ++++++-
.../org/apache/juneau/rest/annotation/License.java | 79 +++++-
.../juneau/rest/annotation/MethodSwagger.java | 154 ++++++++---
.../org/apache/juneau/rest/annotation/Path.java | 78 +++++-
.../org/apache/juneau/rest/annotation/Query.java | 88 +++++-
.../juneau/rest/annotation/ResourceSwagger.java | 164 +++++++----
.../apache/juneau/rest/annotation/Response.java | 97 ++++++-
.../juneau/rest/annotation/ResponseHeader.java | 80 +++++-
.../juneau/rest/annotation/ResponseStatus.java | 241 ++++++++++++++---
.../{ResponseStatus.java => ResponseStatuses.java} | 8 +-
.../org/apache/juneau/rest/annotation/Schema.java | 73 ++++-
.../org/apache/juneau/rest/annotation/Status.java | 132 ---------
.../org/apache/juneau/rest/annotation/Tag.java | 96 ++++++-
.../rest/annotation/doc-files/Body_Example.png | Bin 0 -> 80182 bytes
.../rest/annotation/doc-files/Body_Swagger.png | Bin 0 -> 54642 bytes
.../apache/juneau/rest/util/AnnotationUtils.java | 29 ++
.../org/apache/juneau/rest/util/RestUtils.java | 16 +-
.../juneau/rest/BasicRestInfoProviderTest.java | 24 +-
.../annotation/ResponseStatusAnnotationTest.java | 42 +--
36 files changed, 1844 insertions(+), 481 deletions(-)
diff --git
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchema.java
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchema.java
index 5ff5921..ac6ca50 100644
---
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchema.java
+++
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchema.java
@@ -52,8 +52,8 @@ public class JsonSchema {
private Map<String,JsonSchema> properties;
private Map<String,JsonSchema> patternProperties;
private Map<String,JsonSchema> dependencies;
- private JsonSchema itemsSchema; // Schema
representation of items
- private JsonSchemaArray itemsSchemaArray; //
SchemaArray representation of items
+ private JsonSchema itemsSchema; //
JsonSchema representation of items
+ private JsonSchemaArray itemsSchemaArray; //
JsonSchemaArray representation of items
private Number multipleOf;
private Number maximum;
private Boolean exclusiveMaximum;
@@ -63,7 +63,7 @@ public class JsonSchema {
private Integer minLength;
private String pattern;
private Boolean additionalItemsBoolean; // Boolean
representation of additionalItems
- private JsonSchemaArray additionalItemsSchemaArray; //
SchemaArray representation of additionalItems
+ private JsonSchemaArray additionalItemsSchemaArray; //
JsonSchemaArray representation of additionalItems
private Integer maxItems;
private Integer minItems;
private Boolean uniqueItems;
@@ -71,7 +71,7 @@ public class JsonSchema {
private Integer minProperties;
private List<String> required;
private Boolean additionalPropertiesBoolean; // Boolean
representation of additionalProperties
- private JsonSchema additionalPropertiesSchema; // Schema
representation of additionalProperties
+ private JsonSchema additionalPropertiesSchema; //
JsonSchema representation of additionalProperties
private List<String> _enum;
private List<JsonSchema> allOf;
private List<JsonSchema> anyOf;
@@ -437,7 +437,7 @@ public class JsonSchema {
for (JsonSchema p : properties) {
if (p.getName() == null)
throw new BeanRuntimeException(JsonSchema.class,
- "Invalid property passed to
Schema.addProperties(). Property name was null.");
+ "Invalid property passed to
JsonSchema.addProperties(). Property name was null.");
setMasterOn(p);
this.properties.put(p.getName(), p);
}
@@ -488,7 +488,7 @@ public class JsonSchema {
for (JsonSchema p : properties) {
if (p.getName() == null)
throw new BeanRuntimeException(JsonSchema.class,
- "Invalid property passed to
Schema.addProperties(). Property name was null.");
+ "Invalid property passed to
JsonSchema.addProperties(). Property name was null.");
setMasterOn(p);
this.patternProperties.put(p.getName(), p);
}
@@ -540,7 +540,7 @@ public class JsonSchema {
* The value of the <property>items</property> property on this
bean, or <jk>null</jk> if it is not set.
* Can be either a {@link JsonSchema} or {@link JsonSchemaArray}
depending on what value was used to set it.
*/
- @Swap(SchemaOrSchemaArraySwap.class)
+ @Swap(JsonSchemaOrSchemaArraySwap.class)
public Object getItems() {
if (itemsSchema != null)
return itemsSchema;
@@ -586,7 +586,7 @@ public class JsonSchema {
* <p>
* Serialization method is a no-op.
*/
- public static class SchemaOrSchemaArraySwap extends
PojoSwap<Object,Object> {
+ public static class JsonSchemaOrSchemaArraySwap extends
PojoSwap<Object,Object> {
@Override /* PojoSwap */
public Object swap(BeanSession session, Object o) throws
SerializeException {
@@ -625,7 +625,7 @@ public class JsonSchema {
setMasterOn(this.itemsSchemaArray);
} else
throw new
BeanRuntimeException(JsonSchemaProperty.class,
- "Invalid attribute type ''{0}'' passed
in. Must be one of the following: Schema, SchemaArray",
+ "Invalid attribute type ''{0}'' passed
in. Must be one of the following: JsonSchema, JsonSchemaArray",
items.getClass().getName());
}
return this;
@@ -872,7 +872,7 @@ public class JsonSchema {
setMasterOn(this.additionalItemsSchemaArray);
} else
throw new
BeanRuntimeException(JsonSchemaProperty.class,
- "Invalid attribute type ''{0}'' passed
in. Must be one of the following: Boolean, SchemaArray",
+ "Invalid attribute type ''{0}'' passed
in. Must be one of the following: Boolean, JsonSchemaArray",
additionalItems.getClass().getName());
}
return this;
@@ -1153,7 +1153,7 @@ public class JsonSchema {
setMasterOn(this.additionalPropertiesSchema);
} else
throw new
BeanRuntimeException(JsonSchemaProperty.class,
- "Invalid attribute type ''{0}'' passed
in. Must be one of the following: Boolean, Schema",
+ "Invalid attribute type ''{0}'' passed
in. Must be one of the following: Boolean, JsonSchema",
additionalProperties.getClass().getName());
}
return this;
@@ -1409,7 +1409,7 @@ public class JsonSchema {
* Sets the master schema for this schema and all child schema objects.
*
* <p>
- * All child elements in a schema should point to a single "master"
schema in order to locate registered SchemaMap
+ * All child elements in a schema should point to a single "master"
schema in order to locate registered JsonSchemaMap
* objects for resolving external schemas.
*
* @param master The master schema to associate on this and all
children. Can be <jk>null</jk>.
diff --git
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaMap.java
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaMap.java
index 6c0073c..7ef9d68 100644
---
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaMap.java
+++
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaMap.java
@@ -55,7 +55,7 @@ public abstract class JsonSchemaMap extends
ConcurrentHashMap<URI,JsonSchema> {
* URIs defined by {@link UriResolver} can be used for values.
*
* @param uri The URI of the schema to retrieve.
- * @return The Schema, or <jk>null</jk> if schema was not located and
could not be loaded.
+ * @return The JsonSchema, or <jk>null</jk> if schema was not located
and could not be loaded.
*/
@Override /* Map */
public JsonSchema get(Object uri) {
@@ -87,7 +87,7 @@ public abstract class JsonSchemaMap extends
ConcurrentHashMap<URI,JsonSchema> {
public JsonSchemaMap add(JsonSchema...schemas) {
for (JsonSchema schema : schemas) {
if (schema.getId() == null)
- throw new RuntimeException("Schema with no ID
passed to SchemaMap.add(Schema...)");
+ throw new RuntimeException("Schema with no ID
passed to JsonSchemaMap.add(Schema...)");
put(schema.getId(), schema);
schema.setSchemaMap(this);
}
diff --git
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaPropertySimpleArray.java
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaPropertySimpleArray.java
index 82073f5..fdd128a 100644
---
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaPropertySimpleArray.java
+++
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaPropertySimpleArray.java
@@ -19,10 +19,10 @@ package org.apache.juneau.dto.jsonschema;
* An instance of this object is equivalent to calling...
*
* <p class='bcode'>
- * SchemaProperty p = <jk>new</jk> SchemaProperty(name)
+ * JsonSchemaProperty p = <jk>new</jk> JsonSchemaProperty(name)
* .setType(JsonType.<jsf>ARRAY</jsf>)
* .setItems(
- * <jk>new</jk> Schema().setType(elementType)
+ * <jk>new</jk> JsonSchema().setType(elementType)
* );
* </p>
*
diff --git
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaRef.java
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaRef.java
index 8f2e19b..5a744bd 100644
---
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaRef.java
+++
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/JsonSchemaRef.java
@@ -23,7 +23,7 @@ import org.apache.juneau.*;
* An instance of this object is equivalent to calling...
*
* <p class='bcode'>
- * Schema s = <jk>new</jk> Schema().setRef(uri);
+ * JsonSchema s = <jk>new</jk> JsonSchema().setRef(uri);
* </p>
*
* <h5 class='section'>See Also:</h5>
diff --git
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/package.html
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/package.html
index 094782e..443f215 100644
---
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/package.html
+++
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/jsonschema/package.html
@@ -247,17 +247,17 @@
</p>
<ul class='spaced-list'>
<li>
- {@link org.apache.juneau.dto.jsonschema.Schema}
- Top level schema object.
+ {@link
org.apache.juneau.dto.jsonschema.JsonSchema} - Top level schema object.
<li>
- {@link
org.apache.juneau.dto.jsonschema.SchemaProperty} - A subclass of
<code>Schema</code> for
+ {@link
org.apache.juneau.dto.jsonschema.JsonSchemaProperty} - A subclass of
<code>Schema</code> for
representing properties.
<li>
- {@link
org.apache.juneau.dto.jsonschema.SchemaPropertySimpleArray} - A convenience
subclass of
+ {@link
org.apache.juneau.dto.jsonschema.JsonSchemaPropertySimpleArray} - A convenience
subclass of
<code>SchemaProperty</code> for representing
properties of simple array types.
<li>
- {@link
org.apache.juneau.dto.jsonschema.SchemaRef} - Represents a URI reference to
another schema.
+ {@link
org.apache.juneau.dto.jsonschema.JsonSchemaRef} - Represents a URI reference to
another schema.
<li>
- {@link
org.apache.juneau.dto.jsonschema.SchemaArray} - An array of <code>Schema</code>
objects.
+ {@link
org.apache.juneau.dto.jsonschema.JsonSchemaArray} - An array of
<code>Schema</code> objects.
<li>
{@link
org.apache.juneau.dto.jsonschema.JsonType} - An enum of possible JSON data
types.
<li>
@@ -302,13 +302,13 @@
</p>
<p class='bcode'>
<jc>// Create the document object model</jc>
- Schema s = <jk>new</jk> Schema()
+ JsonSchema s = <jk>new</jk> JsonSchema()
.setTitle(<js>"Example Schema"</js>)
.setType(JsonType.<jsf>OBJECT</jsf>)
.addProperties(
- <jk>new</jk> SchemaProperty(<js>"firstName"</js>,
JsonType.<jsf>STRING</jsf>),
- <jk>new</jk> SchemaProperty(<js>"lastName"</js>,
JsonType.<jsf>STRING</jsf>),
- <jk>new</jk> SchemaProperty(<js>"age"</js>,
JsonType.<jsf>INTEGER</jsf>)
+ <jk>new</jk> JsonSchemaProperty(<js>"firstName"</js>,
JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk> JsonSchemaProperty(<js>"lastName"</js>,
JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk> JsonSchemaProperty(<js>"age"</js>,
JsonType.<jsf>INTEGER</jsf>)
.setDescription(<js>"Age in years"</js>)
.setMinimum(0)
)
@@ -360,40 +360,40 @@
This document can be constructing using the following
code:
</p>
<p class='bcode'>
- Schema s = <jk>new</jk> Schema()
+ JsonSchema s = <jk>new</jk> JsonSchema()
.setId(<js>"http://some.site.somewhere/entry-schema#";</js>)
.setSchemaVersionId(<js>"http://json-schema.org/draft-04/schema#";</js>)
.setDescription(<js>"schema for an fstab entry"</js>)
.setType(JsonType.<jsf>OBJECT</jsf>)
.addRequired(<js>"storage"</js>)
.addProperties(
- <jk>new</jk> SchemaProperty(<js>"storage"</js>)
+ <jk>new</jk> JsonSchemaProperty(<js>"storage"</js>)
.setType(JsonType.<jsf>OBJECT</jsf>)
.addOneOf(
- <jk>new</jk>
SchemaRef(<js>"#/definitions/diskDevice"</js>),
- <jk>new</jk>
SchemaRef(<js>"#/definitions/diskUUID"</js>),
- <jk>new</jk>
SchemaRef(<js>"#/definitions/nsf"</js>),
- <jk>new</jk>
SchemaRef(<js>"#/definitions/tmpfs"</js>)
+ <jk>new</jk>
JsonSchemaRef(<js>"#/definitions/diskDevice"</js>),
+ <jk>new</jk>
JsonSchemaRef(<js>"#/definitions/diskUUID"</js>),
+ <jk>new</jk>
JsonSchemaRef(<js>"#/definitions/nsf"</js>),
+ <jk>new</jk>
JsonSchemaRef(<js>"#/definitions/tmpfs"</js>)
),
- <jk>new</jk> SchemaProperty(<js>"fstype"</js>)
+ <jk>new</jk> JsonSchemaProperty(<js>"fstype"</js>)
.addEnum(<js>"ext3"</js>, <js>"ext4"</js>,
<js>"btrfs"</js>),
- <jk>new</jk>
SchemaPropertySimpleArray(<js>"options"</js>, JsonType.<jsf>STRING</jsf>)
+ <jk>new</jk>
JsonSchemaPropertySimpleArray(<js>"options"</js>, JsonType.<jsf>STRING</jsf>)
.setMinItems(1)
.setUniqueItems(<jk>true</jk>),
- <jk>new</jk> SchemaProperty(<js>"readonly"</js>)
+ <jk>new</jk> JsonSchemaProperty(<js>"readonly"</js>)
.setType(JsonType.<jsf>BOOLEAN</jsf>)
)
.addDefinition(<js>"diskDevice"</js>,
- <jk>new</jk> Schema()
+ <jk>new</jk> JsonSchema()
)
.addDefinition(<js>"diskUUID"</js>,
- <jk>new</jk> Schema()
+ <jk>new</jk> JsonSchema()
)
.addDefinition(<js>"nfs"</js>,
- <jk>new</jk> Schema()
+ <jk>new</jk> JsonSchema()
)
.addDefinition(<js>"tmpfs"</js>,
- <jk>new</jk> Schema()
+ <jk>new</jk> JsonSchema()
);
<jc>// Serialize to JSON</jc>
@@ -430,22 +430,22 @@
)
<jk>public class</jk> JsonSchemaResource <jk>extends</jk>
BasicRestServletJena {
- <jk>private</jk> Schema <jf>schema</jf>; <jc>// The schema
document</jc>
+ <jk>private</jk> JsonSchema <jf>schema</jf>; <jc>// The
schema document</jc>
<jd>/** Servlet initialization */</jd>
<ja>@Override</ja>
<jk>public void</jk> init() {
<jk>try</jk> {
- <jf>schema</jf> = <jk>new</jk> Schema()
+ <jf>schema</jf> = <jk>new</jk> JsonSchema()
.setId(<js>"http://example.com/sample-schema#";</js>)
.setSchemaVersionUri(<js>"http://json-schema.org/draft-04/schema#";</js>)
.setTitle(<js>"Example Schema"</js>)
.setType(JsonType.<jsf>OBJECT</jsf>)
.addProperties(
- <jk>new</jk>
SchemaProperty(<js>"firstName"</js>, JsonType.<jsf>STRING</jsf>),
- <jk>new</jk>
SchemaProperty(<js>"lastName"</js>, JsonType.<jsf>STRING</jsf>),
- <jk>new</jk>
SchemaProperty(<js>"age"</js>, JsonType.<jsf>INTEGER</jsf>)
+ <jk>new</jk>
JsonSchemaProperty(<js>"firstName"</js>, JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk>
JsonSchemaProperty(<js>"lastName"</js>, JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk>
JsonSchemaProperty(<js>"age"</js>, JsonType.<jsf>INTEGER</jsf>)
.setDescription(<js>"Age in years"</js>)
.setMinimum(0)
)
@@ -457,7 +457,7 @@
<jd>/** GET request handler */</jd>
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
- <jk>public</jk> Schema getSchema() <jk>throws</jk> Exception {
+ <jk>public</jk> JsonSchema getSchema() <jk>throws</jk>
Exception {
<jk>return</jk> <jf>schema</jf>;
}
@@ -466,7 +466,7 @@
* Replaces the schema document with the specified content, and
then mirrors it as the response.
*/</jd>
<ja>@RestMethod</ja>(name=<jsf>PUT</jsf>, path=<js>"/"</js>)
- <jk>public</jk> Schema setSchema(<ja>@Body</ja> Schema schema)
<jk>throws</jk> Exception {
+ <jk>public</jk> JsonSchema setSchema(<ja>@Body</ja> JsonSchema
schema) <jk>throws</jk> Exception {
<jk>this</jk>.<jf>schema</jf> = schema;
<jk>return</jk> <jk>this</jk>.<jf>schema</jf>;
}
@@ -526,7 +526,7 @@
</p>
<p class='bcode'>
<jc>// Use parser to load JSON-Schema document into JSON-Schema
DTOs</jc>
- Schema schema = JsonParser.<jsf>DEFAULT</jsf>.parse(json,
Schema.<jk>class</jk>);
+ Schema schema = JsonParser.<jsf>DEFAULT</jsf>.parse(json,
JsonSchema.<jk>class</jk>);
</p>
<p>
Schema objects can also be constructed from the other
media types using the appropriate parsers.
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 58a15da..3709010 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -12451,25 +12451,7 @@
<ul>
<li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#description() description()}
<li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#required() required()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#type() type()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#format() format()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#pattern() pattern()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#collectionFormat() collectionFormat()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#maximum() maximum()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#minimum() minimum()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#multipleOf() multipleOf()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#maxLength() maxLength()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#minLength() minLength()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#maxItems() maxItems()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#minItems() minItems()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#allowEmptyValue() allowEmptyValue()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#exclusiveMaximum() exclusiveMaximum()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#exclusiveMinimum() exclusiveMinimum()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#uniqueItems() uniqueItems()}
<li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#schema() schema()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#_default() _default()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#_enum() _enum()}
- <li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#items() items()}
<li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#example() example()}
<li class='jf'>{@link
org.apache.juneau.rest.annotation.Body#examples() examples()}
</ul>
@@ -20567,7 +20549,7 @@
href='org/apache/juneau/dto/jsonschema/package-summary.html#TOC'>JSON Schema
DTO</a> API.
</ul>
<p>
- The resource consists of a pre-initialized {@link
org.apache.juneau.dto.jsonschema.Schema} object.
+ The resource consists of a pre-initialized {@link
org.apache.juneau.dto.jsonschema.JsonSchema} object.
Pointing a browser to the resource shows the following:
</p>
<p class='bcode w800'>
@@ -20614,21 +20596,21 @@
<jk>public class</jk> JsonSchemaResource <jk>extends</jk>
BasicRestServletJena {
<jk>private static final long</jk> <jsf>serialVersionUID</jsf>
= 1L;
- <jk>private</jk> Schema schema; <jc>// The schema document</jc>
+ <jk>private</jk> JsonSchema schema; <jc>// The schema
document</jc>
<ja>@Override</ja> /* Servlet */
<jk>public void</jk> init() {
<jk>try</jk> {
- <jf>schema</jf> = <jk>new</jk> Schema()
+ <jf>schema</jf> = <jk>new</jk> JsonSchema()
.setId(<js>"http://example.com/sample-schema#";</js>)
.setSchemaVersionUri(<js>"http://json-schema.org/draft-04/schema#";</js>)
.setTitle(<js>"Example Schema"</js>)
.setType(JsonType.<jsf>OBJECT</jsf>)
.addProperties(
- <jk>new</jk>
SchemaProperty(<js>"firstName"</js>, JsonType.<jsf>STRING</jsf>),
- <jk>new</jk>
SchemaProperty(<js>"lastName"</js>, JsonType.<jsf>STRING</jsf>),
- <jk>new</jk>
SchemaProperty(<js>"age"</js>, JsonType.<jsf>INTEGER</jsf>)
+ <jk>new</jk>
JsonSchemaProperty(<js>"firstName"</js>, JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk>
JsonSchemaProperty(<js>"lastName"</js>, JsonType.<jsf>STRING</jsf>),
+ <jk>new</jk>
JsonSchemaProperty(<js>"age"</js>, JsonType.<jsf>INTEGER</jsf>)
.setDescription(<js>"Age in years"</js>)
.setMinimum(0)
)
@@ -20640,7 +20622,7 @@
<jd>/** GET request handler */</jd>
<ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>)
- <jk>public</jk> Schema getSchema() <jk>throws</jk> Exception {
+ <jk>public</jk> JsonSchema getSchema() <jk>throws</jk>
Exception {
<jk>return</jk> <jf>schema</jf>;
}
@@ -20649,7 +20631,7 @@
* Replaces the schema document with the specified content, and
then mirrors it as the response.
*/</jd>
<ja>@RestMethod</ja>(name=<jsf>PUT</jsf>, path=<js>"/"</js>)
- <jk>public</jk> Schema setSchema(<ja>@Body</ja> Schema schema)
<jk>throws</jk> Exception {
+ <jk>public</jk> JsonSchema setSchema(<ja>@Body</ja> JsonSchema
schema) <jk>throws</jk> Exception {
<jk>this</jk>.<jf>schema</jf> = schema;
<jk>return</jk> schema;
}
@@ -25964,7 +25946,7 @@
</ul>
</li>
<li>
- New JSON-Schema {@link
org.apache.juneau.dto.jsonschema.SchemaMap} class for supporting linked schemas.
+ New JSON-Schema {@link
org.apache.juneau.dto.jsonschema.JsonSchemaMap} class for supporting linked
schemas.
</li>
<li>
Serializers will no longer throw an exception
when <code>maxDepth</code> setting is reached, and will instead simply ignore
content below the specified depth.<br>
diff --git a/juneau-doc/src/main/javadoc/resources/juneau-code.css
b/juneau-doc/src/main/javadoc/resources/juneau-code.css
index d58bb74..e74d129 100644
--- a/juneau-doc/src/main/javadoc/resources/juneau-code.css
+++ b/juneau-doc/src/main/javadoc/resources/juneau-code.css
@@ -120,6 +120,7 @@ un { color: DarkBlue; } /* Number value */
us { color: #00B; } /* String value */
/*--- Manifest-file code effects ---*/
+mc { color: green; }
mk { color: DarkRed; font-weight: bold; }
mv { color: DarkBlue;}
diff --git
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetCreate.java
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetCreate.java
index 3dcaa0b..913e607 100644
---
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetCreate.java
+++
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetCreate.java
@@ -33,7 +33,7 @@ public class PetCreate {
}
public static PetCreate example() {
- return new PetCreate("Doggie", 9.99f, "doc", new String[]
{"friendly","cute"});
+ return new PetCreate("Doggie", 9.99f, "Dog", new String[]
{"friendly","cute"});
}
public String getName() {
diff --git
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
index ce2ebba..d903e2b 100644
---
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
+++
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
@@ -23,7 +23,6 @@ import java.util.Map;
import org.apache.juneau.dto.html5.*;
import org.apache.juneau.internal.*;
-import org.apache.juneau.json.*;
import org.apache.juneau.microservice.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.rest.annotation.*;
@@ -168,10 +167,9 @@ public class PetStoreResource extends BasicRestServletJena
{
)
)
public Ok addPet(
- @Body(description="Pet object that needs to be added to
the store") PetCreate pet
+ @Body(description="Pet object to add to the store")
PetCreate pet
) throws IdConflict, NotAcceptable, UnsupportedMediaType {
- JsonSerializer.DEFAULT_LAX_READABLE.println(pet);
store.create(pet);
return OK;
}
@@ -280,8 +278,14 @@ public class PetStoreResource extends BasicRestServletJena
{
public Collection<Pet> findPetsByStatus(
@Query(
name="status",
- description="Status values that need to be
considered for filter",
+ description="Status values that need to be
considered for filter.",
required="true",
+ type="array",
+ items=@Items(
+ type="string",
+ _enum="AVAILABLE,PENDING,SOLD",
+ _default="AVAILABLE"
+ ),
example="['AVAILABLE','PENDING']"
)
PetStatus[] status
@@ -328,7 +332,7 @@ public class PetStoreResource extends BasicRestServletJena {
)
)
public Ok deletePet(
- @Header(name="api_key", example="foobar") String
apiKey,
+ @Header(name="api_key", description="Security API key",
required="true", example="foobar") String apiKey,
@Path(name="petId", description="Pet id to delete",
example="123") long petId
) throws IdNotFound, NotAcceptable {
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 886b3ea..c377a4a 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
@@ -836,8 +836,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.value(), location,
locationArgs);
- om.appendSkipEmpty("name", vs.resolve(a.name()));
+ ObjectMap om = newMap(vs, new ObjectMap(), a.api(), location,
locationArgs);
+ om.appendSkipEmpty("name", vs.resolve(firstNonEmpty(a.name(),
a.value())));
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;
@@ -899,7 +899,15 @@ public class BasicRestInfoProvider implements
RestInfoProvider {
boolean isOk = "ok".equals(in), isBody = "body".equals(in);
- example =
JsonParser.DEFAULT.parse(JsonSerializer.DEFAULT.serialize(example), type);
+ String sex = example.toString();
+ if (RestUtils.isJson(sex)) {
+ example =
JsonParser.DEFAULT.parse(JsonSerializer.DEFAULT.serialize(example), type);
+ } else {
+ ClassMeta<?> cm = js.getClassMeta(type);
+ if (cm.hasStringTransform()) {
+ example =
cm.getStringTransform().transform(sex);
+ }
+ }
String examplesKey = isOk ? "examples" : "x-examples"; //
Parameters don't have an examples attribute.
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
index 37154f5..5a1c34a 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestContext.java
@@ -4305,8 +4305,8 @@ public final class RestContext extends BeanContext {
else if (a instanceof Responses)
for (Response r :
((Responses)a).value())
rp[i] = new
RestParamDefaults.ResponseObject(method, r, t, ps, rp[i]);
- else if (a instanceof ResponseStatus) {
- for (Status rs :
((ResponseStatus)a).value())
+ else if (a instanceof ResponseStatuses)
{
+ for (ResponseStatus rs :
((ResponseStatuses)a).value())
rp[i] = new
RestParamDefaults.ResponseStatusObject(method, rs, t, ps, rp[i]);
if (rp[i] == null)
rp[i] = new
RestParamDefaults.ResponseStatusObject(method, null, t, ps, rp[i]);
@@ -4340,8 +4340,8 @@ public final class RestContext extends BeanContext {
else if (a instanceof Responses)
for (Response r :
((Responses)a).value())
rp[i] = new
RestParamDefaults.ResponseObject(method, r, t, ps, rp[i]);
- else if (a instanceof ResponseStatus) {
- for (Status rs :
((ResponseStatus)a).value())
+ else if (a instanceof ResponseStatuses) {
+ for (ResponseStatus rs :
((ResponseStatuses)a).value())
rp[i] = new
RestParamDefaults.ResponseStatusObject(method, rs, t, ps, rp[i]);
if (rp[i] == null)
rp[i] = new
RestParamDefaults.ResponseStatusObject(method, null, t, ps, rp[i]);
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestParamDefaults.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestParamDefaults.java
index 1425dfd..bd3956b 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestParamDefaults.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestParamDefaults.java
@@ -718,7 +718,7 @@ class RestParamDefaults {
static final class ResponseStatusObject extends RestMethodParam {
- protected ResponseStatusObject(Method method, Status a, Type
type, PropertyStore ps, RestMethodParam existing) {
+ protected ResponseStatusObject(Method method, ResponseStatus a,
Type type, PropertyStore ps, RestMethodParam existing) {
super(RESPONSE_STATUS, method, "", type, getMetaData(a,
castOrNull(existing, ResponseStatusObject.class)));
}
@@ -748,16 +748,14 @@ class RestParamDefaults {
return v;
}
- private static ObjectMap getMetaData(Status a,
ResponseStatusObject existing) {
+ private static ObjectMap getMetaData(ResponseStatus a,
ResponseStatusObject existing) {
ObjectMap om = existing == null ? new ObjectMap() :
existing.metaData;
if (a == null)
return om;
om = om.modifiable();
int status = firstNonZero(a.code(), a.value(), 200);
ObjectMap om2 = om.getObjectMap(String.valueOf(status),
true);
- om2
- .appendSkipEmpty("description",
joinnl(a.description()))
- ;
+ merge(om2, a);
return om;
}
}
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 456dce2..cc5f889 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
@@ -20,6 +20,10 @@ import java.lang.annotation.*;
import java.nio.charset.*;
import java.util.logging.*;
+import org.apache.juneau.*;
+import org.apache.juneau.json.*;
+import org.apache.juneau.jsonschema.*;
+
/**
* REST request body annotation.
*
@@ -52,12 +56,40 @@ import java.util.logging.*;
* </p>
*
* <p>
+ * This annotation is also used for supplying swagger information about the
body of the request.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Body</ja>(
+ * description=<js>"Pet object to add to the store"</js>,
+ * required=<js>"true"</js>,
+ *
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Body</ja>({
+ * <js>"description: 'Pet object to add to the store',"</js>,
+ * <js>"required: true,"</js>,
+ * <js>"example:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']},"</js>
+ * <js>"x-extra: 'extra field'"</js>
+ * })
+ * </p>
+ *
+ * <p>
+ * This is used to populate the auto-generated Swagger documentation and UI:
+ *
+ * <p>
+ * <img class='bordered' src='doc-files/Body_Swagger.png' style='width:860px'>
+ *
+ * <p>
* This annotation can be applied to the following:
* <ul class='spaced-list'>
* <li>
- * Parameters on a {@link RestMethod @RestMethod}-annotated
method.
+ * Parameters on a {@link RestMethod @RestMethod}-annotated method.
* <li>
- * POJO classes.
+ * POJO classes used as parameters on a {@link RestMethod
@RestMethod}-annotated method.
* </ul>
*
* <p>
@@ -106,22 +138,28 @@ import java.util.logging.*;
* <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='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
* Annotation values are coalesced from multiple sources in the
following order of precedence:
* <ol>
- * <li><ja>@Body</ja> annotation fields on parameter.
- * <li><ja>@Body</ja> annotation on class.
+ * <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>
*
- *
* <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="https://swagger.io/specification/v2/#parameterObject";>Swagger
Specification > Parameter Object</a>
* </ul>
*/
@Documented
@@ -130,59 +168,6 @@ import java.util.logging.*;
@Inherited
public @interface Body {
- /**
- * Free-form swagger for the swagger field
<code>/paths/{path}/{method}/parameters(in=body)/#</code>
- *
- * <p>
- * This is a JSON object that makes up the swagger information for this
parameter-info.
- *
- * <p>
- * The following are completely equivalent ways of defining the swagger
description of the body:
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
- * <jk>public void</jk> addPet(
- * <ja>@Body</ja>(description=<js>"Pet object to add to
the store"</js>) Pet input
- * ) {...}
- * </p>
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
- * <jk>public void</jk> addPet(
- * <ja>@Body</ja>(<js>"{description:'Pet object to add to
the store'}"</js>) Pet input
- * ) {...}
- * </p>
- *
- * <p>
- * The reasons why you may want to use this field include:
- * <ul>
- * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
- * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
- * </ul>
- *
- * <h5 class='section'>Notes:</h5>
- * <ul class='spaced-list'>
- * <li>
- * The format 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>body=<js>"{description:'Pet object to
add to the store'}"</js></code>
- * <li><code>body=<js>"description:'Pet object to
add to the store'"</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>).
- * <li>
- * Resolution of variables is delayed until request time
and occurs before parsing.
- * <br>This allows you to, for example, pull in a JSON
construct from a properties file based on the locale of the HTTP request.
- * <li>
- * Swagger field values defined in this value can be
overridden by the other specific annotation fields (e.g {@link #description()}).
- * </ul>
- */
- String[] value() default {};
-
-
//=================================================================================================================
// Attributes common to all ParameterInfos
//=================================================================================================================
@@ -277,7 +262,7 @@ public @interface Body {
* <ul>
*
<li><code>schema=<js>"{type:'string',format:'binary'}"</js></code>
*
<li><code>schema=<js>"type:'string',format:'binary'"</js></code>
- * <ul>
+ * </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>).
@@ -286,22 +271,210 @@ public @interface Body {
Schema schema() default @Schema;
/**
+ * Serialized example for the body.
+ *
+ * <p>
+ * This is the JSON or String representation of an example of the body.
+ *
+ * <p>
+ * This value is converted to a POJO and then serialized to all the
registered serializers on the REST method to produce examples for all
+ * supported language types.
+ * <br>These values are then used to automatically populate the {@link
#examples} field.
+ *
+ * <p class='bcode w800'>
+ * <jc>// A JSON representation of a PetCreate object.</jc>
+ * <ja>@Body</ja>(
+ *
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
+ * )
+ * </p>
+ * <p>
+ * <img class='bordered' src='doc-files/Body_Example.png'
style='width:860px'>
+ *
+ * <p>
+ * There are several other options for defining this example:
+ * <ul class='spaced-list'>
+ * <li>
+ * Defining an <js>"x-example"</js> field in the inherited
Swagger JSON body field (classpath file or
<code><ja>@ResourceSwagger</ja>(value)</code>/<code><ja>@MethodSwagger</ja>(value)</code>).
+ * <li>
+ * Defining an <js>"x-example"</js> field in the Swagger
Schema Object for the body (including referenced <js>"$ref"</js> schemas).
+ * </ul>
+ *
+ * <p>
+ * The latter is important because Juneau also supports auto-generation
of JSON-Schema from POJO classes using {@link JsonSchemaSerializer} which has
several of it's own
+ * options for auto-detecting and calculation POJO examples.
+ *
+ * <p>
+ * In particular, examples can be defined via static methods, fields,
and annotations on the classes themselves.
+ *
+ * <p class='bcode w800'>
+ * <jc>// Annotation on class.</jc>
+ *
<ja>@Example</ja>(<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>)
+ * <jk>public class</jk> PetCreate {
+ * ...
+ * }
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Annotation on static method.</jc>
+ * <jk>public class</jk> PetCreate {
+ *
+ * <ja>@Example</ja>
+ * <jk>public static</jk> PetCreate <jsm>sample</jsm>() {
+ * <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
+ * }
+ * }
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Static method with specific name 'example'.</jc>
+ * <jk>public class</jk> PetCreate {
+ *
+ * <jk>public static</jk> PetCreate <jsm>example</jsm>() {
+ * <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
+ * }
+ * }
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Static field.</jc>
+ * <jk>public class</jk> PetCreate {
+ *
+ * <ja>@Example</ja>
+ * <jk>public static</jk> PetCreate <jsf>EXAMPLE</jsf> =
<jk>new</jk> PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk>
String[] {<js>"friendly"</js>,<js>"cute"</js>});
+ * }
+ * </p>
+ *
+ * <p>
+ * Examples can also be specified via generic properties as well using
the {@link BeanContext#BEAN_examples} property at either the class or method
level.
+ * <p class='bcode w800'>
+ * <jc>// Examples defined at class level.</jc>
+ * <ja>@RestResource</ja>(
+ * properties={
+ * <ja>@Property</ja>(
+ * name=<jsf>BEAN_examples</jsf>,
+ *
value=<js>"{'org.apache.juneau.examples.rest.petstore.PetCreate':
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}"</js>
+ * )
+ * }
+ * )
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is any JSON if the object can be converted
to a POJO using {@link JsonParser#DEFAULT} or a simple String if the object
+ * can be converted from a String.
+ * <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[] example() default {};
+
+ /**
* Defines the swagger field
<code>/paths/{path}/{method}/parameters(in=body)/#/x-examples</code>.
*
* <p>
* This is a JSON object whose keys are media types and values are
string representations of that value.
*
+ * <p>
+ * In general you won't need to populate this value directly since it
will automatically be calculated based on the value provided in the {@link
#example()} field.
+ * <br>However, this field allows you to override the behavior and show
examples for only specified media types or different examples for different
media types.
+ *
+ * <p class='bcode w800'>
+ * <jc>// A JSON representation of a PetCreate object.</jc>
+ * <ja>@Body</ja>(
+ * examples={
+ *
<js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
+ *
<js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
+ * }
+ * )
+ * </p>
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
* <li>
- * The format is a JSON object.
- * <br>Multiple lines are concatenated with newlines.
+ * The format is a Simplified JSON object with string keys
(media type) and string values (example for that media type) .
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable:
* <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>
+ * Resolution of variables is delayed until request time
and occurs before parsing.
+ * <br>This allows you to, for example, pull in a JSON
construct from a properties file based on the locale of the HTTP request.
* </ul>
*/
String[] examples() default {};
- String[] example() default {};
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/parameters(in=body)/#</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
parameter-info.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the body:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <jk>public void</jk> addPet(
+ * <ja>@Body</ja>(
+ * description=<js>"Pet object to add to the
store"</js>,
+ * required=<js>"true"</js>,
+ *
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
+ * ) Pet input
+ * ) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <jk>public void</jk> addPet(
+ * <ja>@Body</ja>({
+ * <js>"description: 'Pet object to add to the
store',"</js>,
+ * <js>"required: true,"</js>,
+ * <js>"example:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
+ * }) Pet input
+ * ) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestMethod</ja>(name=<jsf>POST</jsf>)
+ * <jk>public void</jk> addPet(
+ * <ja>@Body</ja>(<js>"$L{petObjectSwagger}"</js>) Pet
input
+ * ) {...}
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>petObjectSwagger</mk> = <mv>{ description: "Pet object to
add to the store", required: true, example:
{name:"Doggie",price:9.99,species:"Dog",tags:["friendly","cute"]} }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Body</ja>(<js>"{description: 'Pet object to add to the
store'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Body</ja>(<js>"description: 'Pet object to add to the
store'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
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 67c3485..802737e 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
@@ -18,13 +18,42 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Swagger schema annotation.
+ * Swagger contact 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.
+ * The contact information for the exposed API.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * contact=<ja>@Contact</ja>(
+ * name=<js>"Juneau Development Team"</js>,
+ * email=<js>"[email protected]"</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>@Contact</ja>({
+ * <js>"name:'Juneau Development Team',"</js>,
+ * <js>"email:'[email protected]',"</js>,
+ * <js>"url:'http://juneau.apache.org',"</js>,
+ * <js>"x-extra:'extra field'"</js>
+ * })
+ * )
+ * )
+ * </p>
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#contactObject";>Swagger Specification
> Contact Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -32,9 +61,82 @@ import java.lang.annotation.*;
@Inherited
public @interface Contact {
- String[] value() default {};
-
String name() default "";
String url() default "";
String email() default "";
+
+ /**
+ * Free-form value for the swagger field <code>/info/contact</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the contact information:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * contact=<ja>@Contact</ja>(
+ * name=<js>"Juneau Development Team"</js>,
+ * email=<js>"[email protected]"</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>@Contact</ja>({
+ * <js>"name: 'Juneau Development
Team',"</js>,
+ * <js>"email:
'[email protected]',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>,
+ * })
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ *
contact=<ja>@Contact</ja>(<js>"$L{contactSwagger}"</js>)
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>contactSwagger</mk> = <mv>{ name: "Juneau Development
Team", email: "[email protected]", url: "http://juneau.apache.org"; }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Contact</ja>(<js>"{name: 'Juneau Development Team'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Contact</ja>(<js>"name: 'Juneau Development Team'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
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 92808e5..f0561b1 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
@@ -15,11 +15,87 @@ package org.apache.juneau.rest.annotation;
/**
* TODO
*
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#externalDocumentationObject";>Swagger
Specification > External Documentation Object</a>
+ * </ul>
*/
public @interface ExternalDocs {
- String[] value() default {};
-
String[] description() default {};
String url() default "";
+
+ /**
+ * Free-form value for External Documentation objects in Swagger
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of documentation:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * externalDocs=<ja>@ExternalDocs</ja>(
+ * description=<js>"Find out more about
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>(
+ * externalDocs=<ja>@ExternalDocs</ja>({
+ * <js>"description: 'Find out more about
Juneau',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>
+ * })
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ *
externalDocs=<ja>@ExternalDocs</ja>(<js>"$L{externalDocsSwagger}"</js>)
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>externalDocsSwagger</mk> = <mv>{ description: "Find out
more about Juneau", url: "http://juneau.apache.org"; }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ *
<ja>@ExternalDocs</ja>(<js>"{url:'http://juneau.apache.org'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ *
<ja>@ExternalDocs</ja>(<js>"url:'http://juneau.apache.org'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
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 0dc1330..d195100 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
@@ -14,11 +14,14 @@ package org.apache.juneau.rest.annotation;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
+import static org.apache.juneau.rest.helper.Ok.*;
import java.lang.annotation.*;
import org.apache.juneau.httppart.*;
import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.exception.*;
+import org.apache.juneau.rest.helper.*;
/**
* Annotation that can be applied to a parameter of a {@link RestMethod
@RestMethod} annotated method to identify it as a form post
@@ -58,6 +61,7 @@ import org.apache.juneau.rest.*;
* <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="https://swagger.io/specification/v2/#parameterObject";>Swagger
Specification > Parameter Object</a>
* </ul>
*/
@Documented
@@ -96,8 +100,6 @@ public @interface FormData {
*/
Class<? extends HttpPartParser> parser() default
HttpPartParser.Null.class;
- String[] api() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/parameters(in=formData)/#/description</code>.
*
@@ -452,4 +454,75 @@ public @interface FormData {
* </ul>
*/
String[] example() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/parameters(in=form)/#</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the form post entry:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@FormData</ja>(
+ * name=<js>"additionalMetadata"</js>,
+ * description=<js>"Additional data to pass to
server"</js>,
+ * example=<js>"Foobar"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@FormData</ja>(
+ * name=<js>"additionalMetadata"</js>,
+ * api={
+ * <js>"description: 'Additional data to pass to
server',"</js>,
+ * <js>"example: 'Foobar'"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@FormData</ja>(
+ * name=<js>"additionalMetadata"</js>,
+ * api=<js>"$L{additionalMetadataSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>additionalMetadataSwagger</mk> = <mv>{ description:
"Additional data to pass to server", example: "Foobar" }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@FormData</ja>(api=<js>"{example: 'Foobar'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@FormData</ja>(api=<js>"example: 'Foobar'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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 {};
}
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 b435ae0..10a86b2 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
@@ -45,6 +45,7 @@ import org.apache.juneau.rest.*;
* <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="https://swagger.io/specification/v2/#parameterObject";>Swagger
Specification > Parameter Object</a>
* </ul>
*/
@Documented
@@ -68,8 +69,6 @@ public @interface Header {
*/
Class<? extends HttpPartParser> parser() default
HttpPartParser.Null.class;
- String[] api() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/parameters(in=header)/#/description</code>.
*
@@ -426,4 +425,77 @@ public @interface Header {
* </ul>
*/
String[] example() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/parameters(in=header)/#</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the request header:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Header</ja>(
+ * name=<js>"api_key"</js>,
+ * description=<js>"Security API key"</js>,
+ * required=<js>"true"</js>,
+ * example=<js>"foobar"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Header</ja>(
+ * name=<js>"api_key"</js>,
+ * api={
+ * <js>"description: 'Security API key',"</js>,
+ * <js>"required: true,"</js>,
+ * <js>"example: 'foobar'"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@Header</ja>(
+ * name=<js>"api_key"</js>,
+ * api=<js>"$L{apiKeySwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>apiKeySwagger</mk> = <mv>{ description: "Security API key",
required: true, example: "foobar" }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Header</ja>(api=<js>"{required: true}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Header</ja>(api=<js>"required: true"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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 {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Items.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Items.java
index 66c0b91..604a52e 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Items.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Items.java
@@ -25,6 +25,11 @@ import java.lang.annotation.*;
* 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.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#itemsObject";>Swagger Specification
> Items Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -32,8 +37,6 @@ import java.lang.annotation.*;
@Inherited
public @interface Items {
- String[] value() default {};
-
String type() default "";
String format() default "";
String collectionFormat() default "";
@@ -51,4 +54,96 @@ public @interface Items {
String uniqueItems() default "";
String[] _default() default {};
String[] _enum() default {};
+
+ /**
+ * Free-form value for Items objects in Swagger
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of an Items object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</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>// Free-form</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</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>// Free-form as part of parent</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * api={
+ * <js>"type:'array',"</js>,
+ * <js>"items: {"</js>,
+ * <js>"type: 'string',"</js>,
+ * <js>"enum:
['AVAILABLE','PENDING','SOLD'],"</js>,
+ * <js>"default: 'AVAILABLE'"</js>,
+ * <js>"}"</js>)
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * type=<js>"array"</js>,
+ * items=<ja>@Items</ja>(<js>"$L{statusItemsSwagger}"</js>)
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>statusItemsSwagger</mk> = <mv>{ type: "string", enum:
["AVAILABLE","PENDING","SOLD"], default: "AVAILABLE" }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Items</ja>(api=<js>"{type: 'string'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Items</ja>(api=<js>"type: 'string'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/License.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/License.java
index 1b93d7d..df415a5 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/License.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/License.java
@@ -25,6 +25,11 @@ import java.lang.annotation.*;
* 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.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#licenseObject";>Swagger Specification
> License Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -32,10 +37,78 @@ import java.lang.annotation.*;
@Inherited
public @interface License {
- String[] value() default {};
-
String name() default "";
String url() default "";
-
+ /**
+ * Free-form value for the swagger field <code>/info/license</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the license information:
+ * <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>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestResource</ja>(
+ *
swagger=<ja>@ResourceSwagger</ja>(<js>"$L{licenseSwagger}"</js>)
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>licenseSwagger</mk> = <mv>{ name: "Apache 2.0", url:
"http://www.apache.org/licenses/LICENSE-2.0.html"; }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@License</ja>(<js>"{name: 'Apache 2.0'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@License</ja>(<js>"name: 'Apache 2.0'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
index ceae960..361587a 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
@@ -23,40 +23,6 @@ package org.apache.juneau.rest.annotation;
public @interface MethodSwagger {
/**
- * Defines the swagger field <code>/paths/{path}/{method}</code>.
- *
- * <p>
- * Used for free-form Swagger documentation of a REST Java method.
- *
- * <h5 class='section'>Example:</h5>
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(
- * swagger=<ja>@MethodSwagger</ja>(
- * <js>"tags:['pet'],"</js>,
- * <js>"security:[ {
petstore_auth:['write:pets','read:pets'] } ]"</js>
- * )
- * )
- * </p>
- *
- * <h5 class='section'>Notes:</h5>
- * <ul class='spaced-list'>
- * <li>
- * The format is a JSON object.
- * <br>Multiple lines are concatenated with newlines.
- * <br>Comments and whitespace are ignored.
- * <br>The leading and trailing <js>'{'</js>/<js>'}'</js>
characters are optional.
- * <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>
- * Values defined on this annotation override values
defined for the method in the class swagger.
- * <li>
- *
- * </ul>
- */
- String[] value() default {};
-
- /**
* Defines the swagger field
<code>/paths/{path}/{method}/summary</code>.
*
* <h5 class='section'>Notes:</h5>
@@ -178,7 +144,7 @@ public @interface MethodSwagger {
* Defines the swagger field
<code>/paths/{path}/{method}/consumes</code>.
*
* <p>
- * Use this value to override the supported <code>CAccept/code> media
types defined by the serializers defined via {@link RestMethod#serializers()}.
+ * Use this value to override the supported <code>Accept</code> media
types defined by the serializers defined via {@link RestMethod#serializers()}.
*
* <h5 class='section'>Notes:</h5>
* <ul class='spaced-list'>
@@ -206,6 +172,7 @@ public @interface MethodSwagger {
* </p>
*
* <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
* <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>).
@@ -312,4 +279,121 @@ public @interface MethodSwagger {
* </ul>
*/
String[] tags() default {};
+
+ /**
+ * Defines the swagger field <code>/paths/{path}/{method}</code>.
+ *
+ * <p>
+ * Used for free-form Swagger documentation of a REST Java method.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * swagger=<ja>@MethodSwagger</ja>(
+ * <js>"tags:['pet'],"</js>,
+ * <js>"security:[ {
petstore_auth:['write:pets','read:pets'] } ]"</js>
+ * )
+ * )
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a JSON object.
+ * <br>Multiple lines are concatenated with newlines.
+ * <br>Comments and whitespace are ignored.
+ * <br>The leading and trailing <js>'{'</js>/<js>'}'</js>
characters are optional.
+ * <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>
+ * Values defined on this annotation override values
defined for the method in the class swagger.
+ * <li>
+ *
+ * </ul>
+ */
+
+ /**
+ * Free-form value for the swagger of a resource method.
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
resource method.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of a resource method:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"POST"</js>,
+ * path=<js>"/pet"</js>,
+ * swagger=<ja>@MethodSwagger</ja>(
+ * summary=<js>"Add pet"</js>,
+ * description=<js>"Adds a new pet to the
store"</js>,
+ * tags=<js>"pet"</js>,
+ * externalDocs=<ja>@ExternalDocs</ja>(
+ * description=<js>"Home page"</js>,
+ * url=<js>"http://juneau.apache.org";</js>
+ * )
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"POST"</js>,
+ * path=<js>"/pet"</js>,
+ * swagger=<ja>@MethodSwagger</ja>({
+ * <js>"summary: 'Add pet',"</js>,
+ * <js>"description: 'Adds a new pet to the
store',"</js>,
+ * <js>"tags: ['pet'],"</js>,
+ * <js>"externalDocs:{"</js>,
+ * <js>"description: 'Home page',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>,
+ * <js>"}"</js>
+ * })
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"POST"</js>,
+ * path=<js>"/pet"</js>,
+ *
swagger=<ja>@MethodSwagger</ja>(<js>"$L{addPetSwagger}"</js>)
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>addPetSwagger</mk> = <mv>{ summary: "Add pet", description:
"Adds a new pet to the store", tags: ["pet"], externalDocs:{ description: "Home
page", url: "http://juneau.apache.org"; } }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@MethodSwagger</ja>(<js>"{summary: 'Add pet'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@MethodSwagger</ja>(<js>"summary: 'Add pet'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] 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 9dc047a..9cc9c4e 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
@@ -36,6 +36,7 @@ import org.apache.juneau.rest.*;
* <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="https://swagger.io/specification/v2/#parameterObject";>Swagger
Specification > Parameter Object</a>
* </ul>
*/
@Documented
@@ -62,8 +63,6 @@ public @interface Path {
*/
Class<? extends HttpPartParser> parser() default
HttpPartParser.Null.class;
- String[] api() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/parameters(in=path)/#/description</code>.
*
@@ -310,4 +309,79 @@ public @interface Path {
* </ul>
*/
String[] example() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/parameters(in=path)/#</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the Path object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Path</ja>(
+ * name=<js>"orderId"</js>,
+ * description=<js>"ID of order to fetch"</js>,
+ * maximum=<js>"1000"</js>,
+ * minimum=<js>"101"</js>,
+ * example=<js>"123"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Path</ja>({
+ * name=<js>"orderId"</js>,
+ * api={
+ * <js>"description: 'ID of order to
fetch',"</js>,
+ * <js>"maximum: 1000,"</js>,
+ * <js>"minimum: 101,"</js>,
+ * <js>"example: 123"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@Path</ja>({
+ * name=<js>"orderId"</js>,
+ * api=<js>"$L{orderIdSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>orderIdSwagger</mk> = <mv>{ description: "ID of order to
fetch", maximum: 1000, minimum: 101, example: 123 }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Path</ja>(api=<js>"{description: 'ID of order to
fetch'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Path</ja>(api=<js>"description: 'ID of order to
fetch''"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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 {};
}
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 a931a9d..aa1e538 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
@@ -54,6 +54,7 @@ import org.apache.juneau.rest.*;
* <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="https://swagger.io/specification/v2/#parameterObject";>Swagger
Specification > Parameter Object</a>
* </ul>
*/
@Documented
@@ -91,8 +92,6 @@ public @interface Query {
*/
Class<? extends HttpPartParser> parser() default
HttpPartParser.Null.class;
- String[] api() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/parameters(in=query)/#/description</code>.
*
@@ -450,4 +449,89 @@ public @interface Query {
* </ul>
*/
String[] example() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/parameters(in=query)/#</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the Query object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * description=<js>"Status values that need to be
considered for filter."</js>,
+ * required=<js>"true"</js>,
+ * type=<js>"array"</js>,
+ * items=<ja>@Items</ja>(
+ * type=<js>"string"</js>,
+ * _enum=<js>"AVAILABLE,PENDING,SOLD"</js>,
+ * _default=<js>"AVAILABLE"</js>
+ * ),
+ * example=<js>"['AVAILABLE','PENDING']"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * api={
+ * <js>"description: 'Status values that need to
be considered for filter.',"</js>,
+ * <js>"required: true,"</js>,
+ * <js>"type: 'array',"</js>,
+ * <js>"items: {"</js>,
+ * <js>"type: 'string',"</js>,
+ * <js>"enum:
'AVAILABLE,PENDING,SOLD',"</js>,
+ * <js>"default: 'AVAILABLE'"</js>,
+ * <js>"}"</js>,
+ * <js>"example: "['AVAILABLE','PENDING']"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@Query</ja>(
+ * name=<js>"status"</js>,
+ * api=<js>"$L{statusSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>statusSwagger</mk> = <mv>{ description: "Status values that
need to be considered for filter.", required: true, type: "array", items:
{type: "string", enum: "AVAILABLE,PENDING,SOLD", default: "AVAILABLE"},
example: "['AVAILABLE','PENDING']" } }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Query</ja>(api=<js>"{description: 'ID of order to
fetch'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Query</ja>(api=<js>"description: 'ID of order to
fetch''"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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 {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
index 58a8a5c..1df8975 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
@@ -22,55 +22,6 @@ package org.apache.juneau.rest.annotation;
*/
public @interface ResourceSwagger {
- /**
- * Defines the the free-form contents of the swagger.
- *
- * <p>
- * Used to populate the auto-generated OPTIONS swagger documentation.
- *
- * <h5 class='section'>Examples:</h5>
- * <p class='bcode'>
- * <ja>@RestResource</ja>(
- * <jc>// Swagger info.</jc>
- * swagger=@ResourceSwagger({
- * <js>"title:'Petstore application',"</js>,
- * <js>"description:"</js>,
- * <js>"'This is a sample server Petstore
server based on the Petstore sample at Swagger.io."</js>,
- * + <js>"\nYou can find out more about
Swagger at <a class=\'link\'
href=\'http://swagger.io\'>http://swagger.io</a>.',"</js>,
- * <js>"contact:{name:'John
Smith',email:'[email protected]'},"</js>,
- * <js>"license:{name:'Apache
2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},"</js>,
- * <js>"version:'2.0',</js>,
- * <js>"termsOfService:'You are on your
own.',"</js>,
- * <js>"tags:[{name:'Java',description:'Java
utility',externalDocs:{description:'Home
page',url:'http://juneau.apache.org'}}],"</js>,
- * <js>"externalDocs:{description:'Home
page',url:'http://juneau.apache.org'}"</js>
- * })
- * )
- * </p>
- * <p class='bcode'>
- * <ja>@RestResource</ja>(
- * <jc>// Swagger info pulled from file.</jc>
- * swagger=@ResourceSwagger("$F{MyResource.json}")
- * )
- * </p>
- *
- * <h5 class='section'>Notes:</h5>
- * <ul class='spaced-list'>
- * <li>
- * The format is a JSON object.
- * <br>Multiple lines are concatenated with newlines.
- * <li>
- * The starting and ending <js>'{'</js>/<js>'}'</js>
characters are optional.
- * <li>
- * If a Swagger JSON file
<code>{resource-class-simple-name}_{locale}.json</code> is present in the same
package on the classpath, the values
- * defined in this annotation will be superimposed on the
values pulled from the Swagger JSON file.
- * <li>
- * The other annotation values defined here are
superimposed on the values defined by this value.
- * <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[] value() default {};
/**
* Defines the swagger field <code>/info/title</code>.
@@ -359,4 +310,119 @@ public @interface ResourceSwagger {
* </ul>
*/
String version() default "";
+
+ /**
+ * Free-form value for the swagger of a resource.
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
resource.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of a resource:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * title=<js>"Petstore application"</js>,
+ * description={
+ * <js>"This is a sample server Petstore
server based on the Petstore sample at Swagger.io."</js>,
+ * <js>"You can find out more about
Swagger at <a class='link'
href='http://swagger.io'>http://swagger.io</a>.";</js>
+ * },
+ * contact=<ja>@Contact</ja>(
+ * name=<js>"John Smith"</js>,
+ * email=<js>"[email protected]"</js>
+ * ),
+ * license=<ja>@License</ja>(
+ * name=<js>"Apache 2.0"</js>,
+ *
url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>
+ * ),
+ * version=<js>"2.0"</js>,
+ * termsOfService=<js>"You are on your own."</js>,
+ * tags={
+ * <ja>@Tag</ja>(
+ * name=<js>"Java"</js>,
+ * description=<js>"Java
utility"</js>,
+ *
externalDocs=<ja>@ExternalDocs</ja>(
+ * description=<js>"Home
page"</js>,
+ *
url=<js>"http://juneau.apache.org";</js>
+ * )
+ * }
+ * },
+ * externalDocs=<ja>@ExternalDocs</ja>(
+ * description=<js>"Home page"</js>,
+ * url=<js>"http://juneau.apache.org";</js>
+ * )
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestResource</ja>(
+ * swagger=@ResourceSwagger({
+ * <js>"title: 'Petstore application',"</js>,
+ * <js>"description: 'This is a sample server
Petstore server based on the Petstore sample at Swagger.io.\nYou can find out
more about Swagger at <a class='link'
href='http://swagger.io'>http://swagger.io</a>.',"</js>,
+ * <js>"contact:{"</js>,
+ * <js>"name: 'John Smith',"</js>,
+ * <js>"email: '[email protected]'"</js>,
+ * <js>"},"</js>,
+ * <js>"license:{"</js>,
+ * <js>"name: 'Apache 2.0',"</js>,
+ * <js>"url:
'http://www.apache.org/licenses/LICENSE-2.0.html'"</js>,
+ * <js>"},"</js>,
+ * <js>"version: '2.0',"</js>,
+ * <js>"termsOfService: 'You are on your
own.',"</js>,
+ * <js>"tags:["</js>,
+ * <js>"{"</js>,
+ * <js>"name: 'Java',"</js>,
+ * <js>"description: 'Java
utility',"</js>,
+ * <js>"externalDocs:{"</js>,
+ * <js>"description: 'Home
page',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>,
+ * <js>"}"</js>,
+ * <js>"}"</js>,
+ * <js>"],"</js>,
+ * <js>"externalDocs:{"</js>,
+ * <js>"description: 'Home page',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>,
+ * <js>"}"</js>
+ * })
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestResource</ja>(
+ *
swagger=@ResourceSwagger(<js>"$F{MyResourceSwagger.json}"</js>)
+ * )
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@ResourceSwagger</ja>(<js>"{title:'Petstore
application'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@ResourceSwagger</ja>(<js>"title:'Petstore
application'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] 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 e8acd8d..3e9cd77 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
@@ -83,12 +83,21 @@ import org.apache.juneau.rest.helper.*;
* <ja>@Response<ja>(
* code=302,
* description=<js>"Redirect"</js>,
- * headers={<js>"Location:{description:'Redirect URI',
type:'string', format:'uri'}"</js>}
+ * headers={
+ * <ja>@ResponseHeader</ja>(
+ * name=<js>"Location"</js>,
+ * type=<js>"string"</js>,
+ * format=<js>"uri"</js>
+ * )
+ * }
* )
* <jk>public class</jk> Redirect { ... }
* </p>
*
- *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#responseObject";>Swagger
Specification > Response Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -105,8 +114,6 @@ public @interface Response {
int value() default 0;
- String[] api() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/responses/{status-code}/description</code>.
*
@@ -195,4 +202,86 @@ public @interface Response {
* </ul>
*/
String[] examples() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/responses/{response}</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the Response object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Response</ja>(
+ * code=302,
+ * description=<js>"Redirect"</js>,
+ * headers={
+ * <ja>@ResponseHeader</ja>(
+ * name=<js>"Location"</js>,
+ * type=<js>"string"</js>,
+ * format=<js>"uri"</js>
+ * )
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Response</ja>(
+ * code=302,
+ * api={
+ * <js>"description: 'Redirect',"</js>,
+ * <js>"headers: {"</js>,
+ * <js>"Location: {"</js>,
+ * <js>"type: 'string',"</js>,
+ * <js>"format: 'uri'"</js>,
+ * <js>"}"</js>,
+ * <js>"}"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@Response</ja>(
+ * code=302,
+ * api=<js>"$L{redirectSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>redirectSwagger</mk> = <mv>{ description: "Redirect",
headers: { Location: { type: "string", format: "uri" } } }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"code"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Response</ja>(api=<js>"{description: 'Redirect'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Response</ja>(api=<js>"description: 'Redirect''"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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 {};
}
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 cf342c5..02b60a1 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
@@ -59,15 +59,18 @@ import org.apache.juneau.utils.*;
* <ja>@ResponseHeader</ja>(name=<js>"X-Rate-Limit"</js>,
type=<js>"integer"</js>, format=<js>"int32"</js>, description=<js>"Calls per
hour allowed by the user."</js>, example=<js>"123"</js>)
* <jk>public static class</jk> RateLimit <jk>extends</jk>
Value<Integer> {}
* </p>
- */
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#headerObject";>Swagger Specification
> Header Object</a>
+ * </ul>
+*/
@Documented
@Target({PARAMETER,TYPE})
@Retention(RUNTIME)
@Inherited
public @interface ResponseHeader {
- String[] api() default {};
-
/**
* The HTTP status (or statuses) of the response.
*
@@ -441,4 +444,75 @@ public @interface ResponseHeader {
* </ul>
*/
String[] example() default {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/responses/{response}/headers/{header}</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
Header object.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the Header object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@ResponseHeader</ja>(
+ * name=<js>"Location"</js>,
+ * description=<js>"The new location of this
resource"</js>,
+ * type=<js>"string"</js>,
+ * format=<js>"uri"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@ResponseHeader</ja>(
+ * name=<js>"Location"</js>,
+ * api={
+ * <js>"description: 'The new location of this
resource',"</js>,
+ * <js>"type: 'string',"</js>,
+ * <js>"format: 'uri'"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@ResponseHeader</ja>(
+ * name=<js>"Location"</js>,
+ * api=<js>"$L{locationSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>locationSwagger</mk> = <mv>{ description: "The new location
of this resource", type: "string", format: "uri" }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"name"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@ResponseHeader</ja>(<js>"{description:'The new location of
this resource'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@ResponseHeader</ja>(<js>"description:'The new location of
this resource'"</js>)
+ * </p>
+ * <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>
+ * 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 {};
}
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 a06a94c..0c817e4 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
@@ -1,37 +1,204 @@
-//
***************************************************************************************************************************
-// * Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file *
-// * distributed with this work for additional information regarding copyright
ownership. The ASF licenses this file *
-// * to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance *
-// * with the License. You may obtain a copy of the License at
*
-// *
*
-// * http://www.apache.org/licenses/LICENSE-2.0
*
-// *
*
-// * Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an *
-// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied. See the License for the *
-// * specific language governing permissions and limitations under the
License. *
-//
***************************************************************************************************************************
-package org.apache.juneau.rest.annotation;
-
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-/**
- * Used to associate multiple {@link Status @Status} 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.
- */
-@Documented
-@Target({PARAMETER,TYPE})
-@Retention(RUNTIME)
-@Inherited
-public @interface ResponseStatus {
-
- /**
- * Specifies one or more {@link Status @Status} annotations to apply to
the same parameter or class.
- */
- Status[] value() default {};
-}
\ No newline at end of file
+//
***************************************************************************************************************************
+// * Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file *
+// * distributed with this work for additional information regarding copyright
ownership. The ASF licenses this file *
+// * to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance *
+// * with the License. You may obtain a copy of the License at
*
+// *
*
+// * http://www.apache.org/licenses/LICENSE-2.0
*
+// *
*
+// * Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an *
+// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied. See the License for the *
+// * specific language governing permissions and limitations under the
License. *
+//
***************************************************************************************************************************
+package org.apache.juneau.rest.annotation;
+
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.utils.*;
+
+/**
+ * Annotation that can be applied to parameters and types to denote them as an
HTTP response status.
+ *
+ * <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.
+ *
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password,
+ * <ja>@ResponseStatus</ja>(code=401,
description=<js>"Invalid user/pw"</js>) Value<Integer> status) {
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * }
+ * </p>
+ *
+ * <p>
+ * The {@link Responses @Responses} annotation can be used to represent
multiple possible response types.
+ *
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password,
+ * <ja>@ResponseStatuses</ja>{
+ * <ja>@ResponseStatus</ja>(200)
+ * <ja>@ResponseStatus</ja>(code=401,
description=<js>"Invalid user/pw"</js>)
+ * }
+ * Value<Integer> status) {
+ *
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * <jk>else</jk>
+ * status.set(200);
+ * }
+ * </p>
+ *
+ * <p>
+ * The other option is to apply this annotation to a subclass of {@link Value}
which often leads to a cleaner
+ * REST method:
+ *
+ * <p class='bcode'>
+ * <ja>@ResponseStatuses</ja>{
+ * <ja>@ResponseStatus</ja>(200)
+ * <ja>@ResponseStatus</ja>(code=401, description=<js>"Invalid
user/pw"</js>)
+ * }
+ * <jk>public class</jk> LoginStatus <jk>extends</jk> Value<Integer>
{}
+ *
+ * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
+ * <jk>public void</jk> login(String username, String password,
LoginStatus status) {
+ * <jk>if</jk> (! isValid(username, password))
+ * status.set(401);
+ * <jk>else</jk>
+ * status.set(200);
+ * }
+ * </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: {
+ * 200: {
+ * description: <js>'OK'</js>
+ * },
+ * 401: {
+ * description: <js>'Invalid user/pw'</js>
+ * }
+ * }
+ * }
+ * }
+ * </p>
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#responseObject";>Swagger
Specification > Response Object</a>
+ * </ul>
+ */
+@Documented
+@Target({})
+@Retention(RUNTIME)
+@Inherited
+public @interface ResponseStatus {
+
+ /**
+ * The HTTP status of the response.
+ */
+ int code() default 0;
+
+ /**
+ * A synonym to {@link #code()}.
+ *
+ * <p>
+ * Useful if you only want to specify a code only.
+ *
+ * <p class='bcode'>
+ * <ja>@ResponseStatus</ja>(200)
+ * </p>
+ */
+ int value() default 0;
+
+ /**
+ * Defines the swagger field
<code>/paths/{path}/{method}/responses/{status-code}/description</code>.
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format 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 {};
+
+ /**
+ * Free-form value for the swagger field
<code>/paths/{path}/{method}/responses/{response}</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
Response object.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the Response object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@ResponseStatus</ja>(
+ * code=401,
+ * description=<js>"Invalid user/pw"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@ResponseStatus</ja>(
+ * code=401,
+ * api={
+ * <js>"description: 'Invalid user/pw'"</js>
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@ResponseStatus</ja>(
+ * code=401,
+ * api=<js>"$L{unauthorizedSwagger}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>unauthorizedSwagger</mk> = <mv>{ description: "Invalid
user/pw" }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * Note that the only swagger field you can't specify
using this value is <js>"code"</js> whose value needs to be known during
servlet initialization.
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@ResponseStatus</ja>(<js>"{description:'Invalid
user/pw'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@ResponseStatus</ja>(<js>"description:'Invalid
user/pw'"</js>)
+ * </p>
+ * <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>
+ * 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 {};
+}
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/ResponseStatuses.java
similarity index 85%
copy from
juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatus.java
copy to
juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatuses.java
index a06a94c..1111aeb 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/ResponseStatuses.java
@@ -18,7 +18,7 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Used to associate multiple {@link Status @Status} annotations to the same
parameter or class.
+ * 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.
@@ -28,10 +28,10 @@ import java.lang.annotation.*;
@Target({PARAMETER,TYPE})
@Retention(RUNTIME)
@Inherited
-public @interface ResponseStatus {
+public @interface ResponseStatuses {
/**
- * Specifies one or more {@link Status @Status} annotations to apply to
the same parameter or class.
+ * Specifies one or more {@link ResponseStatus @ResponseStatus}
annotations to apply to the same parameter or class.
*/
- Status[] value() default {};
+ ResponseStatus[] value() default {};
}
\ No newline at end of file
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Schema.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Schema.java
index 26f0e40..07e1fa0 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Schema.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Schema.java
@@ -27,6 +27,11 @@ import org.apache.juneau.rest.*;
* 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.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#schemaObject";>Swagger Specification
> Schema Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -34,8 +39,6 @@ import org.apache.juneau.rest.*;
@Inherited
public @interface Schema {
- String[] value() default {};
-
/**
* Defines the swagger field
<code>/paths/{path}/{method}/[parameters(in=body)|responses]/schema/$ref</code>.
*
@@ -464,4 +467,70 @@ public @interface Schema {
String[] examples() default {};
boolean ignore() default false;
+
+ /**
+ * Free-form value for Schema objects in Swagger
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
field.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of a Schema object:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@Schema</ja>(
+ * type=<js>"array"</js>,
+ * items=<ja>@Items</ja>(
+ * $ref=<js>"#/definitions/Pet"</js>
+ * )
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@Schema</ja>(
+ * <js>"type: 'array',"</js>,
+ * <js>"items: {"</js>,
+ * <js>"$ref: '#/definitions/Pet'"</js>,
+ * <js>"}"</js>
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form using variables</jc>
+ * <ja>@Schema</ja>(<js>"$L{petArraySwagger}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>petArraySwagger</mk> = <mv>{ type: "array", items: { $ref:
"#/definitions/Pet" } }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this field from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Schema</ja>(<js>"{type: 'array'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Schema</ja>(<js>"type: 'array'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable.
+ * <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>
+ * 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[] value() default {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Status.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Status.java
deleted file mode 100644
index a9942dc..0000000
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Status.java
+++ /dev/null
@@ -1,132 +0,0 @@
-//
***************************************************************************************************************************
-// * Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file *
-// * distributed with this work for additional information regarding copyright
ownership. The ASF licenses this file *
-// * to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance *
-// * with the License. You may obtain a copy of the License at
*
-// *
*
-// * http://www.apache.org/licenses/LICENSE-2.0
*
-// *
*
-// * Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an *
-// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied. See the License for the *
-// * specific language governing permissions and limitations under the
License. *
-//
***************************************************************************************************************************
-package org.apache.juneau.rest.annotation;
-
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-import org.apache.juneau.utils.*;
-
-/**
- * Annotation that can be applied to parameters and types to denote them as an
HTTP response status.
- *
- * <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.
- *
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- * <jk>public void</jk> login(String username, String password,
- * <ja>@Status</ja>(code=401, description=<js>"Invalid
user/pw"</js>) Value<Integer> status) {
- * <jk>if</jk> (! isValid(username, password))
- * status.set(401);
- * }
- * </p>
- *
- * <p>
- * The {@link Responses @Responses} annotation can be used to represent
multiple possible response types.
- *
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- * <jk>public void</jk> login(String username, String password,
- * <ja>@ResponseStatus</ja>{
- * <ja>@Status</ja>(200)
- * <ja>@Status</ja>(code=401,
description=<js>"Invalid user/pw"</js>)
- * }
- * Value<Integer> status) {
- *
- * <jk>if</jk> (! isValid(username, password))
- * status.set(401);
- * <jk>else</jk>
- * status.set(200);
- * }
- * </p>
- *
- * <p>
- * The other option is to apply this annotation to a subclass of {@link Value}
which often leads to a cleaner
- * REST method:
- *
- * <p class='bcode'>
- * <ja>@ResponseStatus</ja>{
- * <ja>@Status</ja>(200)
- * <ja>@Status</ja>(code=401, description=<js>"Invalid
user/pw"</js>)
- * }
- * <jk>public class</jk> LoginStatus <jk>extends</jk> Value<Integer>
{}
- *
- * <ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/user/login"</js>)
- * <jk>public void</jk> login(String username, String password,
LoginStatus status) {
- * <jk>if</jk> (! isValid(username, password))
- * status.set(401);
- * <jk>else</jk>
- * status.set(200);
- * }
- * </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: {
- * 200: {
- * description: <js>'OK'</js>
- * },
- * 401: {
- * description: <js>'Invalid user/pw'</js>
- * }
- * }
- * }
- * }
- * </p>
- */
-@Documented
-@Target({})
-@Retention(RUNTIME)
-@Inherited
-public @interface Status {
-
- /**
- * The HTTP status of the response.
- */
- int code() default 0;
-
- /**
- * A synonym to {@link #code()}.
- *
- * <p>
- * Useful if you only want to specify a code only.
- *
- * <p class='bcode'>
- * <ja>@Status</ja>(200)
- * </p>
- */
- int value() default 0;
-
- /**
- * Defines the swagger field
<code>/paths/{path}/{method}/responses/{status-code}/description</code>.
- *
- * <h5 class='section'>Notes:</h5>
- * <ul class='spaced-list'>
- * <li>
- * The format 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 {};
-}
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 4cb9df1..beeb2e1 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
@@ -25,6 +25,11 @@ import java.lang.annotation.*;
* 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.
+ *
+ * <h5 class='section'>See Also:</h5>
+ * <ul>
+ * <li class='link'><a class="doclink"
href="https://swagger.io/specification/v2/#tagObject";>Swagger Specification
> Tag Object</a>
+ * </ul>
*/
@Documented
@Target({PARAMETER,TYPE})
@@ -32,9 +37,96 @@ import java.lang.annotation.*;
@Inherited
public @interface Tag {
- String[] value() default {};
-
String name() default "";
+ String value() default "";
String[] description() default {};
ExternalDocs externalDocs() default @ExternalDocs;
+
+ /**
+ * Free-form value for the swagger field <code>/tags/[#]</code>
+ *
+ * <p>
+ * This is a JSON object that makes up the swagger information for this
Tag object.
+ *
+ * <p>
+ * The following are completely equivalent ways of defining the swagger
description of the resource tags:
+ * <p class='bcode w800'>
+ * <jc>// Normal</jc>
+ * <ja>@RestResource</ja>(
+ * tags={
+ * <ja>@Tag</ja>(
+ * name=<js>"pet"</js>,
+ * description=<js>"Everything about your
Pets"</js>,
+ * externalDocs=<ja>@ExternalDocs</ja>(
+ * description="<js>Find out
more"</js>,
+ *
url=<js>"http://juneau.apache.org";</js>
+ * }
+ * )
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form</jc>
+ * <ja>@RestResource</ja>(
+ * tags={
+ * <ja>@Tag</ja>(
+ * name=<js>"pet"</js>,
+ * api={
+ * <js>"name: 'pet',"</js>,
+ * <js>"description: 'Everything
about your Pets',"</js>,
+ * <js>"externalDocs: {"</js>,
+ * <js>"description: 'Find
out more',"</js>,
+ * <js>"url:
'http://juneau.apache.org'"</js>
+ * <js>"}"</js>
+ * }
+ * )
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <jc>// Free-form with variables</jc>
+ * <ja>@RestResource</ja>(
+ * tags={
+ * <ja>@Tag</ja>(
+ * name=<js>"pet"</js>,
+ * api=<js>"$L{petTagSwagger}"</js>
+ * )
+ * }
+ * )
+ * </p>
+ * <p class='bcode w800'>
+ * <mc>// Contents of MyResource.properties</mc>
+ * <mk>petTagSwagger</mk> = <mv>{ name: "pet", description:
"Everything about your Pets", externalDocs: { description: "Find out more",
url: "http://juneau.apache.org"; } }</mv>
+ * </p>
+ *
+ * <p>
+ * The reasons why you may want to use this field include:
+ * <ul>
+ * <li>You want to pull in the entire Swagger JSON definition for
this body from an external source such as a properties file.
+ * <li>You want to add extra fields to the Swagger documentation
that are not officially part of the Swagger specification.
+ * </ul>
+ *
+ * <h5 class='section'>Notes:</h5>
+ * <ul class='spaced-list'>
+ * <li>
+ * The format is a Simplified JSON object.
+ * <li>
+ * The leading/trailing <code>{ }</code> characters are
optional.
+ * <br>The following two example are considered equivalent:
+ * <p class='bcode w800'>
+ * <ja>@Tag</ja>(api=<js>"{description: 'Everything about your
Pets'}"</js>)
+ * </p>
+ * <p class='bcode w800'>
+ * <ja>@Tag</ja>(api=<js>"description: 'Everything about your
Pets'"</js>)
+ * </p>
+ * <li>
+ * Multiple lines are concatenated with newlines so that
you can format the value to be readable:
+ * <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>
+ * 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 {};
}
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Example.png
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Example.png
new file mode 100644
index 0000000..21447e2
Binary files /dev/null and
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Example.png
differ
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Swagger.png
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Swagger.png
new file mode 100644
index 0000000..ed8dfc2
Binary files /dev/null and
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/doc-files/Body_Swagger.png
differ
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/AnnotationUtils.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/AnnotationUtils.java
index c3ea808..e8a3b46 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/AnnotationUtils.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/AnnotationUtils.java
@@ -231,6 +231,22 @@ public class AnnotationUtils {
* @param a The annotation.
* @return The same map with merged results, or a new map if the map
was <jk>null</jk>.
*/
+ public static ObjectMap merge(ObjectMap om, ResponseStatus a) {
+ if (empty(a))
+ return om;
+ om = newMap(om);
+ return om
+ .appendSkipEmpty("_value", joinnl(a.api()))
+ .appendSkipEmpty("description",
joinnl(a.description()));
+ }
+
+ /**
+ * Merges the contents of the specified annotation into the specified
map.
+ *
+ * @param om The map to add the annotation values to.
+ * @param a The annotation.
+ * @return The same map with merged results, or a new map if the map
was <jk>null</jk>.
+ */
public static ObjectMap merge(ObjectMap om, Path a) {
if (empty(a))
return om;
@@ -466,6 +482,19 @@ public class AnnotationUtils {
* @param a The annotation to check.
* @return <jk>true</jk> if the specified annotation contains all
default values.
*/
+ public static boolean empty(ResponseStatus a) {
+ if (a == null)
+ return true;
+ return
+ empty(a.description(), a.api());
+ }
+
+ /**
+ * Returns <jk>true</jk> if the specified annotation contains all
default values.
+ *
+ * @param a The annotation to check.
+ * @return <jk>true</jk> if the specified annotation contains all
default values.
+ */
public static boolean empty(Schema a) {
if (a == null)
return true;
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/RestUtils.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/RestUtils.java
index 8e699dc..e0b3f4c 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/RestUtils.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/util/RestUtils.java
@@ -366,12 +366,22 @@ public final class RestUtils {
* @throws ParseException
*/
public static Object parseAnything(String s) throws ParseException {
+ if (isJson(s))
+ return JsonParser.DEFAULT.parse(s, Object.class);
+ return s;
+ }
+
+ public static boolean isJson(String s) {
if (s == null)
- return null;
+ return false;
char c1 = StringUtils.firstNonWhitespaceChar(s), c2 =
StringUtils.lastNonWhitespaceChar(s);
if (c1 == '{' && c2 == '}' || c1 == '[' && c2 == ']' || c1 ==
'\'' && c2 == '\'')
- return JsonParser.DEFAULT.parse(s, Object.class);
- return s;
+ return true;
+ if (StringUtils.isOneOf(s, "true","false","null"))
+ return true;
+ if (StringUtils.isNumeric(s))
+ return true;
+ return false;
}
/**
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 05abba4..abb5fa8 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
@@ -391,7 +391,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',
description:'b-description', externalDocs: { description:'b-description',
url:'b-url' } } ")
+ tags=@Tag(name="b-name",api=" {
description:'b-description', externalDocs: { description:'b-description',
url:'b-url' } } ")
)
)
public static class C04 {}
@@ -431,7 +431,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',description:'c-description',externalDocs:{description:'c-description',url:'c-url'}}")
+
@Tag(name="s-name",api="{description:'c-description',externalDocs:{description:'c-description',url:'c-url'}}")
}
)
)
@@ -2016,7 +2016,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{description:'a-100-description'}}}}}"))
public static class OA02 {
@RestMethod(name=GET,path="/path/{foo}/responses/100")
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2030,7 +2030,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{description:'a-100-description'}}}}}"))
public static class OA03 {
@RestMethod(name=GET,path="/path/{foo}/responses/100",swagger=@MethodSwagger("responses:{100:{description:'b-100-description'}}"))
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2090,7 +2090,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{headers:{'X-Foo':{description:'b-description',type:'integer',format:'int32'}}}}}}}"))
public static class OB02 {
@RestMethod(name=GET,path="/path/{foo}/responses/100")
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2104,7 +2104,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{headers:{'X-Foo':{description:'b-description',type:'integer',format:'int32'}}}}}}}"))
public static class OB03 {
@RestMethod(name=GET,path="/path/{foo}/responses/100",swagger=@MethodSwagger("responses:{100:{headers:{'X-Foo':{description:'c-description',type:'integer',format:'int32'}}}}"))
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2164,7 +2164,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{example:{foo:'b'}}}}}}"))
public static class OC02 {
@RestMethod(name=GET,path="/path/{foo}/responses/100")
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2178,7 +2178,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{example:{foo:'b'}}}}}}"))
public static class OC03 {
@RestMethod(name=GET,path="/path/{foo}/responses/100",swagger=@MethodSwagger("responses:{100:{example:{foo:'c'}}}"))
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2238,7 +2238,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{examples:{foo:{bar:'b'}}}}}}}"))
public static class OD02 {
@RestMethod(name=GET,path="/path/{foo}/responses/100")
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2252,7 +2252,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{examples:{foo:{bar:'b'}}}}}}}"))
public static class OD03 {
@RestMethod(name=GET,path="/path/{foo}/responses/100",swagger=@MethodSwagger("responses:{100:{examples:{foo:{bar:'c'}}}}"))
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2312,7 +2312,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{schema:{$ref:'b'}}}}}}"))
public static class OE02 {
@RestMethod(name=GET,path="/path/{foo}/responses/100")
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
@@ -2326,7 +2326,7 @@ public class BasicRestInfoProviderTest {
@RestResource(swagger=@ResourceSwagger("paths:{'/path/{foo}/responses/100':{get:{responses:{100:{schema:{$ref:'b'}}}}}}"))
public static class OE03 {
@RestMethod(name=GET,path="/path/{foo}/responses/100",swagger=@MethodSwagger("responses:{100:{schema:{$ref:'c'}}}}"))
- public Foo doFoo(@ResponseStatus Value<Integer> foo) {
+ public Foo doFoo(@ResponseStatuses Value<Integer> foo) {
return null;
}
}
diff --git
a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/annotation/ResponseStatusAnnotationTest.java
b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/annotation/ResponseStatusAnnotationTest.java
index f9ec610..52fd90a 100644
---
a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/annotation/ResponseStatusAnnotationTest.java
+++
b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/annotation/ResponseStatusAnnotationTest.java
@@ -22,7 +22,7 @@ import org.junit.*;
import org.junit.runners.*;
/**
- * Tests related to @ResponseStatus annotation.
+ * Tests related to @ResponseStatuses annotation.
*/
@SuppressWarnings("javadoc")
@FixMethodOrder(MethodSorters.NAME_ASCENDING)
@@ -40,32 +40,32 @@ public class ResponseStatusAnnotationTest {
}
//=================================================================================================================
- // @ResponseStatus on POJO
+ // @ResponseStatuses on POJO
//=================================================================================================================
@RestResource
public static class SA {
- @ResponseStatus({
- @Status(code=100),
- @Status(code=101)
+ @ResponseStatuses({
+ @ResponseStatus(code=100),
+ @ResponseStatus(code=101)
})
public static class SA01 {}
@RestMethod(name=GET,path="/code")
public void sa01(SA01 r) {}
- @ResponseStatus({
- @Status(100),
- @Status(101)
+ @ResponseStatuses({
+ @ResponseStatus(100),
+ @ResponseStatus(101)
})
public static class SA02 {}
@RestMethod(name=GET,path="/salue")
public void sa02(SA02 r) {}
- @ResponseStatus({
- @Status(code=100, description="a"),
- @Status(code=101, description="a\nb")
+ @ResponseStatuses({
+ @ResponseStatus(code=100, description="a"),
+ @ResponseStatus(code=101, description="a\nb")
})
public static class SA03 {}
@@ -93,7 +93,7 @@ public class ResponseStatusAnnotationTest {
}
//=================================================================================================================
- // @ResponseStatus on parameter
+ // @ResponseStatuses on parameter
//=================================================================================================================
@RestResource
@@ -102,9 +102,9 @@ public class ResponseStatusAnnotationTest {
@RestMethod(name=GET,path="/code")
public void sb01(
- @ResponseStatus({
- @Status(code=100),
- @Status(code=101)
+ @ResponseStatuses({
+ @ResponseStatus(code=100),
+ @ResponseStatus(code=101)
})
SB01 r
) {}
@@ -113,9 +113,9 @@ public class ResponseStatusAnnotationTest {
@RestMethod(name=GET,path="/salue")
public void sb02(
- @ResponseStatus({
- @Status(100),
- @Status(101)
+ @ResponseStatuses({
+ @ResponseStatus(100),
+ @ResponseStatus(101)
})
SB02 r
) {}
@@ -124,9 +124,9 @@ public class ResponseStatusAnnotationTest {
@RestMethod(name=GET,path="/description")
public void sb03(
- @ResponseStatus({
- @Status(code=100, description="a"),
- @Status(code=101, description="a\nb")
+ @ResponseStatuses({
+ @ResponseStatus(code=100,
description="a"),
+ @ResponseStatus(code=101,
description="a\nb")
})
SB03 r
) {}
--
To stop receiving notification emails like this one, please contact
[email protected].
