juneau-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jamesbog...@apache.org
Subject [02/11] incubator-juneau git commit: JUNEAU-16 - Support for Swagger documentation
Date Fri, 07 Oct 2016 16:33:44 GMT
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/FormData.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/FormData.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/FormData.java
new file mode 100755
index 0000000..279f366
--- /dev/null
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/FormData.java
@@ -0,0 +1,98 @@
+// ***************************************************************************************************************************
+// * 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.server.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.server.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method
+ * 	to identify it as a form post entry converted to a POJO.
+ *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"POST"</js>)
+ * 	<jk>public void</jk> doPost(RestRequest req, RestResponse res,
+ * 				<ja>@FormData</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@FormData</ja>(<js>"p2"</js>) String p2, <ja>@FormData</ja>(<js>"p3"</js>) UUID p3) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	This is functionally equivalent to the following code...
+ * </p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"POST"</js>)
+ * 	<jk>public void</jk> doPost(RestRequest req, RestResponse res) {
+ * 		<jk>int</jk> p1 = req.getFormData(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
+ * 		String p2 = req.getFormData(String.<jk>class</jk>, <js>"p2"</js>);
+ * 		UUID p3 = req.getFormData(UUID.<jk>class</jk>, <js>"p3"</js>);
+ * 		...
+ * 	}
+ * </p>
+ *
+ * <h6 class='topic'>Important note concerning FORM posts</h6>
+ * <p>
+ * This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody(Class)} method
+ * 	for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet
+ * 	API to parse the body content as key-value pairs resulting in empty content.
+ * <p>
+ * The {@link Query @Query} annotation can be used to retrieve a URL parameter
+ * 	in the URL string without triggering the servlet to drain the body content.
+ *
+ * @author James Bognar (james.bognar@salesforce.com)
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface FormData {
+
+	/**
+	 * URL parameter name.
+	 */
+	String value();
+
+	/**
+	 * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
+	 * <p>
+	 * 	Normally, we expect single parameters to be specified in UON notation for representing
+	 * 	collections of values (e.g. <js>"key=(1,2,3)"</js>.
+	 * 	This annotation allows the use of multi-part parameters to represent collections
+	 * 	(e.g. <js>"key=1&key=2&key=3"</js>.
+	 * <p>
+	 *		This setting should only be applied to Java parameters of type array or Collection.
+	 */
+	boolean multipart() default false;
+
+	/**
+	 * The expected format of the request parameter.
+	 * <p>
+	 * Possible values:
+	 * <ul class='spaced-list'>
+	 * 	<li><js>"UON"</js> - URL-Encoded Object Notation.<br>
+	 *			This notation allows for request parameters to contain arbitrarily complex POJOs.
+	 * 	<li><js>"PLAIN"</js> - Plain text.<br>
+	 *			This treats request parameters as plain text.<br>
+	 *			Only POJOs directly convertable from <l>Strings</l> can be represented in parameters when using this mode.
+	 * 	<li><js>"INHERIT"</js> (default) - Inherit from the {@link RestServletContext#REST_paramFormat} property on the servlet method or class.
+	 * </ul>
+	 * <p>
+	 * Note that the parameter value <js>"(foo)"</js> is interpreted as <js>"(foo)"</js> when using plain mode, but
+	 * 	<js>"foo"</js> when using UON mode.
+	 */
+	String format() default "INHERIT";
+}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasFormData.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasFormData.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasFormData.java
new file mode 100755
index 0000000..b2d47e9
--- /dev/null
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasFormData.java
@@ -0,0 +1,95 @@
+// ***************************************************************************************************************************
+// * 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.server.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.server.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method
+ * 	to identify whether or not the request has the specified multipart form POST parameter.
+ * <p>
+ * Note that this can be used to detect the existence of a parameter when it's not set to a particular value.
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"POST"</js>)
+ * 	<jk>public void</jk> doPost(<ja>@HasFormData</ja>(<js>"p1"</js>) <jk>boolean</jk> p1) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	This is functionally equivalent to the following code...
+ * </p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"POST"</js>)
+ * 	<jk>public void</jk> doPost(RestRequest req) {
+ * 		<jk>boolean</jk> p1 = req.hasFormData(<js>"p1"</js>);
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * The following table shows the behavioral differences between <code>@HasFormData</code> and <code>@FormData</code>...
+ * <table class='styled'>
+ * 	<tr>
+ * 		<th><code>Body content</code></th>
+ * 		<th><code><ja>@HasFormData</ja>(<js>"a"</js>)</code></th>
+ * 		<th><code><ja>@FormData</ja>(<js>"a"</js>)</code></th>
+ * 	</tr>
+ * 	<tr>
+ * 		<td><code>a=foo</code></td>
+ * 		<td><code><jk>true</jk></td>
+ * 		<td><code><js>"foo"</js></td>
+ * 	</tr>
+ * 	<tr>
+ * 		<td><code>a=</code></td>
+ * 		<td><code><jk>true</jk></td>
+ * 		<td><code><js>""</js></td>
+ * 	</tr>
+ * 	<tr>
+ * 		<td><code>a</code></td>
+ * 		<td><code><jk>true</jk></td>
+ * 		<td><code><jk>null</jk></td>
+ * 	</tr>
+ * 	<tr>
+ * 		<td><code>b=foo</code></td>
+ * 		<td><code><jk>false</jk></td>
+ * 		<td><code><jk>null</jk></td>
+ * 	</tr>
+ * </table>
+ *
+ * <h6 class='topic'>Important note concerning FORM posts</h6>
+ * <p>
+ * This annotation should not be combined with the {@link Body @Body} annotation or {@link RestRequest#getBody(Class)} method
+ * 	for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet API to parse the body
+ * 	content as key-value pairs, resulting in empty content.
+ * <p>
+ * The {@link HasQuery @HasQuery} annotation can be used to check for the existing of a URL parameter
+ * 	in the URL string without triggering the servlet to drain the body content.
+ *
+ * @author James Bognar (james.bognar@salesforce.com)
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface HasFormData {
+
+	/**
+	 * URL parameter name.
+	 */
+	String value();
+}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasParam.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasParam.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasParam.java
deleted file mode 100755
index c177ccd..0000000
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasParam.java
+++ /dev/null
@@ -1,95 +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.server.annotation;
-
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-import org.apache.juneau.server.*;
-
-/**
- * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method
- * 	to identify whether or not the request has the specified GET or POST parameter.
- * <p>
- * Note that this can be used to detect the existence of a parameter when it's not set to a particular value.
- * <h6 class='topic'>Example</h6>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(<ja>@HasParam</ja>(<js>"p1"</js>) <jk>boolean</jk> p1) {
- * 		...
- * 	}
- * </p>
- * <p>
- * 	This is functionally equivalent to the following code...
- * </p>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req) {
- * 		<jk>boolean</jk> p1 = req.hasParameter(<js>"p1"</js>);
- * 		...
- * 	}
- * </p>
- * <p>
- * The following table shows the behavioral differences between <code>@HasParam</code> and <code>@Param</code>...
- * <table class='styled'>
- * 	<tr>
- * 		<th><code>URL</code></th>
- * 		<th><code><ja>@HasParam</ja>(<js>"a"</js>)</code></th>
- * 		<th><code><ja>@Param</ja>(<js>"a"</js>)</code></th>
- * 	</tr>
- * 	<tr>
- * 		<td><code>?a=foo</code></td>
- * 		<td><code><jk>true</jk></td>
- * 		<td><code><js>"foo"</js></td>
- * 	</tr>
- * 	<tr>
- * 		<td><code>?a=</code></td>
- * 		<td><code><jk>true</jk></td>
- * 		<td><code><js>""</js></td>
- * 	</tr>
- * 	<tr>
- * 		<td><code>?a</code></td>
- * 		<td><code><jk>true</jk></td>
- * 		<td><code><jk>null</jk></td>
- * 	</tr>
- * 	<tr>
- * 		<td><code>?b=foo</code></td>
- * 		<td><code><jk>false</jk></td>
- * 		<td><code><jk>null</jk></td>
- * 	</tr>
- * </table>
- *
- * <h6 class='topic'>Important note concerning FORM posts</h6>
- * <p>
- * This annotation should not be combined with the {@link Content @Content} annotation or {@link RestRequest#getInput(Class)} method
- * 	for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet API to parse the body
- * 	content as key-value pairs, resulting in empty content.
- * <p>
- * The {@link HasQParam @HasQParam} annotation can be used to check for the existing of a URL parameter
- * 	in the URL string without triggering the servlet to drain the body content.
- *
- * @author James Bognar (james.bognar@salesforce.com)
- */
-@Documented
-@Target(PARAMETER)
-@Retention(RUNTIME)
-@Inherited
-public @interface HasParam {
-
-	/**
-	 * URL parameter name.
-	 */
-	String value();
-}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQParam.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQParam.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQParam.java
deleted file mode 100755
index 4de22ab..0000000
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQParam.java
+++ /dev/null
@@ -1,61 +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.server.annotation;
-
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-import org.apache.juneau.server.*;
-
-/**
- * Identical to {@link HasParam @HasParam}, but only checks the existing of the parameter in the
- * 	URL string, not URL-encoded form posts.
- * <p>
- * Unlike {@link HasParam @HasParam}, using this annotation does not result in the servlet reading the contents
- * 	of URL-encoded form posts.
- * Therefore, this annotation can be used in conjunction with the {@link Content @Content} annotation
- * 	or {@link RestRequest#getInput(Class)} method for <code>application/x-www-form-urlencoded POST</code> calls.
- *
- * <h6 class='topic'>Example</h6>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doPost(<ja>@HasQParam</ja>(<js>"p1"</js>) <jk>boolean</jk> p1, <ja>@Content</ja> Bean myBean) {
- * 		...
- * 	}
- * </p>
- * <p>
- * 	This is functionally equivalent to the following code...
- * </p>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req) {
- * 		<jk>boolean</jk> p1 = req.hasQueryParameter(<js>"p1"</js>);
- * 		...
- * 	}
- * </p>
- *
- * @author James Bognar (james.bognar@salesforce.com)
- */
-@Documented
-@Target(PARAMETER)
-@Retention(RUNTIME)
-@Inherited
-public @interface HasQParam {
-
-	/**
-	 * URL parameter name.
-	 */
-	String value();
-}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQuery.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQuery.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQuery.java
new file mode 100755
index 0000000..ad17d35
--- /dev/null
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/HasQuery.java
@@ -0,0 +1,61 @@
+// ***************************************************************************************************************************
+// * 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.server.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.server.*;
+
+/**
+ * Identical to {@link HasFormData @HasFormData}, but only checks the existing of the parameter in the
+ * 	URL string, not URL-encoded form posts.
+ * <p>
+ * Unlike {@link HasFormData @HasFormData}, using this annotation does not result in the servlet reading the contents
+ * 	of URL-encoded form posts.
+ * Therefore, this annotation can be used in conjunction with the {@link Body @Body} annotation
+ * 	or {@link RestRequest#getBody(Class)} method for <code>application/x-www-form-urlencoded POST</code> calls.
+ *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * 	<jk>public void</jk> doPost(<ja>@HasQuery</ja>(<js>"p1"</js>) <jk>boolean</jk> p1, <ja>@Body</ja> Bean myBean) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	This is functionally equivalent to the following code...
+ * </p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req) {
+ * 		<jk>boolean</jk> p1 = req.hasQueryParameter(<js>"p1"</js>);
+ * 		...
+ * 	}
+ * </p>
+ *
+ * @author James Bognar (james.bognar@salesforce.com)
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface HasQuery {
+
+	/**
+	 * URL parameter name.
+	 */
+	String value();
+}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/Param.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Param.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Param.java
deleted file mode 100755
index f4f5ef8..0000000
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Param.java
+++ /dev/null
@@ -1,98 +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.server.annotation;
-
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-import org.apache.juneau.server.*;
-
-/**
- * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method
- * 	to identify it as a URL query parameter converted to a POJO.
- *
- * <h6 class='topic'>Example</h6>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
- * 				<ja>@Param</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@Param</ja>(<js>"p2"</js>) String p2, <ja>@Param</ja>(<js>"p3"</js>) UUID p3) {
- * 		...
- * 	}
- * </p>
- * <p>
- * 	This is functionally equivalent to the following code...
- * </p>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res) {
- * 		<jk>int</jk> p1 = req.getParam(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
- * 		String p2 = req.getParam(String.<jk>class</jk>, <js>"p2"</js>);
- * 		UUID p3 = req.getParam(UUID.<jk>class</jk>, <js>"p3"</js>);
- * 		...
- * 	}
- * </p>
- *
- * <h6 class='topic'>Important note concerning FORM posts</h6>
- * <p>
- * This annotation should not be combined with the {@link Content @Content} annotation or {@link RestRequest#getInput(Class)} method
- * 	for <code>application/x-www-form-urlencoded POST</code> posts, since it will trigger the underlying servlet
- * 	API to parse the body content as key-value pairs resulting in empty content.
- * <p>
- * The {@link QParam @QParam} annotation can be used to retrieve a URL parameter
- * 	in the URL string without triggering the servlet to drain the body content.
- *
- * @author James Bognar (james.bognar@salesforce.com)
- */
-@Documented
-@Target(PARAMETER)
-@Retention(RUNTIME)
-@Inherited
-public @interface Param {
-
-	/**
-	 * URL parameter name.
-	 */
-	String value();
-
-	/**
-	 * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
-	 * <p>
-	 * 	Normally, we expect single parameters to be specified in UON notation for representing
-	 * 	collections of values (e.g. <js>"&key=(1,2,3)"</js>.
-	 * 	This annotation allows the use of multi-part parameters to represent collections
-	 * 	(e.g. <js>"&key=1&key=2&key=3"</js>.
-	 * <p>
-	 *		This setting should only be applied to Java parameters of type array or Collection.
-	 */
-	boolean multipart() default false;
-
-	/**
-	 * The expected format of the request parameter.
-	 * <p>
-	 * Possible values:
-	 * <ul class='spaced-list'>
-	 * 	<li><js>"UON"</js> - URL-Encoded Object Notation.<br>
-	 *			This notation allows for request parameters to contain arbitrarily complex POJOs.
-	 * 	<li><js>"PLAIN"</js> - Plain text.<br>
-	 *			This treats request parameters as plain text.<br>
-	 *			Only POJOs directly convertable from <l>Strings</l> can be represented in parameters when using this mode.
-	 * 	<li><js>"INHERIT"</js> (default) - Inherit from the {@link RestServletContext#REST_paramFormat} property on the servlet method or class.
-	 * </ul>
-	 * <p>
-	 * Note that the parameter value <js>"(foo)"</js> is interpreted as <js>"(foo)"</js> when using plain mode, but
-	 * 	<js>"foo"</js> when using UON mode.
-	 */
-	String format() default "INHERIT";
-}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/Path.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Path.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Path.java
new file mode 100755
index 0000000..f5f90ad
--- /dev/null
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Path.java
@@ -0,0 +1,74 @@
+// ***************************************************************************************************************************
+// * 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.server.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+/**
+ * Annotation that can be applied to a parameter of a {@link RestMethod} annotated method
+ * 	to identify it as a variable in a URL path pattern converted to a POJO.
+ *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * 			<ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> UUID baz) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	The <ja>@Path</ja> annotation is optional if the parameters are specified immediately
+ * 	following the <code>RestRequest</code> and <code>RestResponse</code> parameters,
+ * 	and are specified in the same order as the variables in the URL path pattern.
+ * 	The following example is equivalent to the previous example.
+ * </p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * 			String foo, <jk>int</jk> bar, UUID baz) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	If the order of parameters is not the default order shown above, the
+ * 	attribute names must be specified (since parameter names are lost during compilation).
+ * 	The following example is equivalent to the previous example, except
+ * 	the parameter order has been switched, requiring the use of the <ja>@Path</ja>
+ * 	annotations.
+ * <p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>, path=<js>"/myurl/{foo}/{bar}/{baz}/*"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * 			<ja>@Path</ja>(<js>"baz"</js>) UUID baz, <ja>@Path</ja>(<js>"foo"</js>) String foo, <ja>@Path</ja>(<js>"bar"</js>) <jk>int</jk> bar) {
+ * 		...
+ * 	}
+ * </p>
+ *
+ * @author James Bognar (james.bognar@salesforce.com)
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Path {
+
+	/**
+	 * URL variable name.
+	 * <p>
+	 * Optional if the attributes are specified in the same order as in the URL path pattern.
+	 */
+	String value() default "";
+}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/QParam.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/QParam.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/QParam.java
deleted file mode 100755
index 32db115..0000000
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/QParam.java
+++ /dev/null
@@ -1,94 +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.server.annotation;
-
-import static java.lang.annotation.ElementType.*;
-import static java.lang.annotation.RetentionPolicy.*;
-
-import java.lang.annotation.*;
-
-import org.apache.juneau.server.*;
-
-/**
- * Identical to {@link Param @Param}, but only retrieves the parameter from the
- * 	URL string, not URL-encoded form posts.
- * <p>
- * Unlike {@link Param @Param}, using this annotation does not result in the servlet reading the contents
- * 	of URL-encoded form posts.
- * Therefore, this annotation can be used in conjunction with the {@link Content @Content} annotation
- * 	or {@link RestRequest#getInput(Class)} method for <code>application/x-www-form-urlencoded POST</code> calls.
- *
- * <h6 class='topic'>Example</h6>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
- * 				<ja>@QParam</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@QParam</ja>(<js>"p2"</js>) String p2, <ja>@QParam</ja>(<js>"p3"</js>) UUID p3) {
- * 		...
- * 	}
- * </p>
- * <p>
- * 	This is functionally equivalent to the following code...
- * </p>
- * <p class='bcode'>
- * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
- * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res) {
- * 		<jk>int</jk> p1 = req.getQueryParameter(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
- * 		String p2 = req.getQueryParameter(String.<jk>class</jk>, <js>"p2"</js>);
- * 		UUID p3 = req.getQueryParameter(UUID.<jk>class</jk>, <js>"p3"</js>);
- * 		...
- * 	}
- * </p>
- *
- * @author James Bognar (james.bognar@salesforce.com)
- */
-@Documented
-@Target(PARAMETER)
-@Retention(RUNTIME)
-@Inherited
-public @interface QParam {
-
-	/**
-	 * URL parameter name.
-	 */
-	String value();
-
-	/**
-	 * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
-	 * <p>
-	 * 	Normally, we expect single parameters to be specified in UON notation for representing
-	 * 	collections of values (e.g. <js>"&key=(1,2,3)"</js>.
-	 * 	This annotation allows the use of multi-part parameters to represent collections
-	 * 	(e.g. <js>"&key=1&key=2&key=3"</js>.
-	 * <p>
-	 *		This setting should only be applied to Java parameters of type array or Collection.
-	 */
-	boolean multipart() default false;
-
-	/**
-	 * The expected format of the request parameter.
-	 * <p>
-	 * Possible values:
-	 * <ul class='spaced-list'>
-	 * 	<li><js>"UON"</js> - URL-Encoded Object Notation.<br>
-	 *			This notation allows for request parameters to contain arbitrarily complex POJOs.
-	 * 	<li><js>"PLAIN"</js> - Plain text.<br>
-	 *			This treats request parameters as plain text.<br>
-	 *			Only POJOs directly convertable from <l>Strings</l> can be represented in parameters when using this mode.
-	 * 	<li><js>"INHERIT"</js> (default) - Inherit from the {@link RestServletContext#REST_paramFormat} property on the servlet method or class.
-	 * </ul>
-	 * <p>
-	 * Note that the parameter value <js>"(foo)"</js> is interpreted as <js>"(foo)"</js> when using plain mode, but
-	 * 	<js>"foo"</js> when using UON mode.
-	 */
-	String format() default "INHERIT";
-}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/Query.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Query.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Query.java
new file mode 100755
index 0000000..8958006
--- /dev/null
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Query.java
@@ -0,0 +1,94 @@
+// ***************************************************************************************************************************
+// * 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.server.annotation;
+
+import static java.lang.annotation.ElementType.*;
+import static java.lang.annotation.RetentionPolicy.*;
+
+import java.lang.annotation.*;
+
+import org.apache.juneau.server.*;
+
+/**
+ * Identical to {@link FormData @FormData}, but only retrieves the parameter from the
+ * 	URL string, not URL-encoded form posts.
+ * <p>
+ * Unlike {@link FormData @FormData}, using this annotation does not result in the servlet reading the contents
+ * 	of URL-encoded form posts.
+ * Therefore, this annotation can be used in conjunction with the {@link Body @Body} annotation
+ * 	or {@link RestRequest#getBody(Class)} method for <code>application/x-www-form-urlencoded POST</code> calls.
+ *
+ * <h6 class='topic'>Example</h6>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res,
+ * 				<ja>@Query</ja>(<js>"p1"</js>) <jk>int</jk> p1, <ja>@Query</ja>(<js>"p2"</js>) String p2, <ja>@Query</ja>(<js>"p3"</js>) UUID p3) {
+ * 		...
+ * 	}
+ * </p>
+ * <p>
+ * 	This is functionally equivalent to the following code...
+ * </p>
+ * <p class='bcode'>
+ * 	<ja>@RestMethod</ja>(name=<js>"GET"</js>)
+ * 	<jk>public void</jk> doGet(RestRequest req, RestResponse res) {
+ * 		<jk>int</jk> p1 = req.getQueryParameter(<jk>int</jk>.<jk>class</jk>, <js>"p1"</js>, 0);
+ * 		String p2 = req.getQueryParameter(String.<jk>class</jk>, <js>"p2"</js>);
+ * 		UUID p3 = req.getQueryParameter(UUID.<jk>class</jk>, <js>"p3"</js>);
+ * 		...
+ * 	}
+ * </p>
+ *
+ * @author James Bognar (james.bognar@salesforce.com)
+ */
+@Documented
+@Target(PARAMETER)
+@Retention(RUNTIME)
+@Inherited
+public @interface Query {
+
+	/**
+	 * URL parameter name.
+	 */
+	String value();
+
+	/**
+	 * Specify <jk>true</jk> if using multi-part parameters to represent collections and arrays.
+	 * <p>
+	 * 	Normally, we expect single parameters to be specified in UON notation for representing
+	 * 	collections of values (e.g. <js>"&key=(1,2,3)"</js>.
+	 * 	This annotation allows the use of multi-part parameters to represent collections
+	 * 	(e.g. <js>"&key=1&key=2&key=3"</js>.
+	 * <p>
+	 *		This setting should only be applied to Java parameters of type array or Collection.
+	 */
+	boolean multipart() default false;
+
+	/**
+	 * The expected format of the request parameter.
+	 * <p>
+	 * Possible values:
+	 * <ul class='spaced-list'>
+	 * 	<li><js>"UON"</js> - URL-Encoded Object Notation.<br>
+	 *			This notation allows for request parameters to contain arbitrarily complex POJOs.
+	 * 	<li><js>"PLAIN"</js> - Plain text.<br>
+	 *			This treats request parameters as plain text.<br>
+	 *			Only POJOs directly convertable from <l>Strings</l> can be represented in parameters when using this mode.
+	 * 	<li><js>"INHERIT"</js> (default) - Inherit from the {@link RestServletContext#REST_paramFormat} property on the servlet method or class.
+	 * </ul>
+	 * <p>
+	 * Note that the parameter value <js>"(foo)"</js> is interpreted as <js>"(foo)"</js> when using plain mode, but
+	 * 	<js>"foo"</js> when using UON mode.
+	 */
+	String format() default "INHERIT";
+}

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/Response.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Response.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Response.java
index 61bd765..848259a 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Response.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Response.java
@@ -51,18 +51,30 @@ public @interface Response {
 	/**
 	 * Optional description.
 	 * <p>
-	 * 	The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
-	 * 	(e.g. <js>"myMethod.res.[code] = foo"</js> or <js>"MyServlet.myMethod.res.[code] = foo"</js>).
+	 * The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
+	 * (e.g. <js>"myMethod.res.[code].description = foo"</js> or <js>"MyServlet.myMethod.res.[code].description = foo"</js>).
 	 * <p>
-	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * Corresponds to the swagger field <code>/paths/{path}/{method}/responses/{code}/description</code>.
 	 */
 	String description() default "";
 
 	/**
-	 * Optional response variables.
+	 * A definition of the response structure.
+	 * <p>
+	 * It can be a primitive, an array or an object.
+	 * If this field does not exist, it means no content is returned as part of the response.
+	 * As an extension to the <a href='http://swagger.io/specification/#schemaObject'>Schema Object</a>, its root type value may also be <js>"file"</js>.
+	 * This SHOULD be accompanied by a relevant produces mime-type.
+	 */
+	String schema() default "";
+
+	/**
+	 * Optional response headers.
 	 * <p>
-	 * 	Response variables can also be defined in the servlet resource bundle.
+	 * Response variables can also be defined in the servlet resource bundle.
 	 * 	(e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>).
 	 */
-	Var[] output() default {};
+	Var[] headers() default {};
 }

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestMethod.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestMethod.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestMethod.java
index a7f745c..a73f84a 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestMethod.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestMethod.java
@@ -108,9 +108,9 @@ public @interface RestMethod {
 	/**
 	 * Overrides the list of serializers assigned at the method level.
 	 * <p>
-	 * Use this annotation when the list of serializers assigned to a method differs from the list of serializers assigned at the servlet level.
+	 * 	Use this annotation when the list of serializers assigned to a method differs from the list of serializers assigned at the servlet level.
 	 * <p>
-	 * To append to the list of serializers assigned at the servlet level, use <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
+	 * 	To append to the list of serializers assigned at the servlet level, use <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
 	 *
 	 * <p class='bcode'>
 	 * 	<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
@@ -132,8 +132,7 @@ public @interface RestMethod {
 	/**
 	 * Used in conjunction with {@link #serializers()} to identify what class-level settings are inherited by the method serializer group.
 	 * <p>
-	 * Possible values:
-	 * </p>
+	 * 	Possible values:
 	 * <ul>
 	 * 	<li>{@link Inherit#SERIALIZERS} - Inherit class-level serializers.
 	 * 	<li>{@link Inherit#PROPERTIES} - Inherit class-level properties.
@@ -155,9 +154,9 @@ public @interface RestMethod {
 	/**
 	 * Overrides the list of parsers assigned at the method level.
 	 * <p>
-	 * Use this annotation when the list of parsers assigned to a method differs from the list of parsers assigned at the servlet level.
+	 * 	Use this annotation when the list of parsers assigned to a method differs from the list of parsers assigned at the servlet level.
 	 * <p>
-	 * To append to the list of serializers assigned at the servlet level, use <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
+	 * 	To append to the list of serializers assigned at the servlet level, use <code>serializersInherit=<jsf>SERIALIZERS</jsf></code>.
 	 *
 	 * <p class='bcode'>
 	 * 	<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
@@ -179,7 +178,7 @@ public @interface RestMethod {
 	/**
 	 * Used in conjunction with {@link #parsers()} to identify what class-level settings are inherited by the method parser group.
 	 * <p>
-	 * Possible values:
+	 * 	Possible values:
 	 * <ul>
 	 * 	<li>{@link Inherit#PARSERS} - Inherit class-level parsers.
 	 * 	<li>{@link Inherit#PROPERTIES} - Inherit class-level properties.
@@ -187,7 +186,6 @@ public @interface RestMethod {
 	 * </ul>
 	 * <p>
 	 * 	For example, to inherit all parsers, properties, and transforms from the servlet class:
-	 * </p>
 	 * <p class='bcode'>
 	 * 	<ja>@RestMethod</ja>(
 	 * 		path=<js>"/foo"</js>,
@@ -201,9 +199,9 @@ public @interface RestMethod {
 	/**
 	 * Appends to the list of {@link Encoder encoders} specified on the servlet.
 	 * <p>
-	 * Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at the servlet level.
+	 * 	Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at the servlet level.
 	 * <p>
-	 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
+	 * 	These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
 	 *
 	 * <p class='bcode'>
 	 * 	<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
@@ -218,8 +216,8 @@ public @interface RestMethod {
 	 * 		}
 	 * 	}
 	 * </p>
-	 *
-	 * If you want to OVERRIDE the set of encoders specified by the servlet, combine this annotation with <code><ja>@RestMethod</ja>(inheritEncoders=<jk>false</jk>)</code>.
+	 * <p>
+	 * 	If you want to OVERRIDE the set of encoders specified by the servlet, combine this annotation with <code><ja>@RestMethod</ja>(inheritEncoders=<jk>false</jk>)</code>.
 	 */
 	Class<? extends Encoder>[] encoders() default {};
 
@@ -231,7 +229,7 @@ public @interface RestMethod {
 	/**
 	 * Same as {@link RestResource#properties()}, except defines property values by default when this method is called.
 	 * <p>
-	 * This is equivalent to simply calling <code>res.addProperties()</code> in the Java method, but is provided for convenience.
+	 * 	This is equivalent to simply calling <code>res.addProperties()</code> in the Java method, but is provided for convenience.
 	 */
 	Property[] properties() default {};
 
@@ -246,36 +244,18 @@ public @interface RestMethod {
 	Class<?>[] pojoSwaps() default {};
 
 	/**
-	 * Possible HTTP response codes from this method.
-	 * <p>
-	 * 	This annotation is provided for documentation purposes.
-	 * 	It is used in conjunction with the following NLS resource bundle keys to populate options pages:
-	 * <ul class='spaced-list'>
-	 * 	<li><js>"(className.?)[javaMethodName].res.[rc]"</js> - Response description (defaults to HTTP status message).
-	 * 		e.g. <js>"MyClass.myMethod.res.404 = Sorry...I couldn't find that."</js> or <js>"myMethod.res.404 = Sorry...I couldn't find that."</js>
-	 * 	<li><js>"(className.?)[javaMethodName].res.[rc].[varCategory].[varName]"</js> - Response variable .
-	 * 		e.g. <js>"MyClass.myMethod.res.302.[header].[Location] = Set to the location where the thing can be found."</js> or  <js>"myMethod.res.302.[header].[Location] = Set to the location where the thing can be found."</js>
-	 * </ul>
-	 * <p>
-	 * Note that you can still define the keys in the resource bundle and not use this annotation.
-	 * However, the annotation is provided if you just want the OPTIONS page to show the possible status codes with
-	 * default HTTP status messages.
-	 */
-	int[] rc() default {};
-
-	/**
 	 * Specifies default values for request headers.
 	 * <p>
-	 * Strings are of the format <js>"Header-Name: header-value"</js>.
+	 * 	Strings are of the format <js>"Header-Name: header-value"</js>.
 	 * <p>
-	 * Affects values returned by {@link RestRequest#getHeader(String)} when the header is not present on the request.
+	 * 	Affects values returned by {@link RestRequest#getHeader(String)} when the header is not present on the request.
 	 * <p>
-	 * The most useful reason for this annotation is to provide a default <code>Accept</code> header when one is not specified
+	 * 	The most useful reason for this annotation is to provide a default <code>Accept</code> header when one is not specified
 	 * 	so that a particular default {@link Serializer} is picked.
 	 * <p>
-	 * Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
+	 * 	Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
 	 * <p>
-	 * Header values specified at the method level override header values specified at the servlet level.
+	 * 	Header values specified at the method level override header values specified at the servlet level.
 	 *
 	 * <dl>
 	 * 	<dt>Example:</dt>
@@ -293,67 +273,146 @@ public @interface RestMethod {
 	String[] defaultRequestHeaders() default {};
 
 	/**
-	 * Optional description.
+	 * Optional summary for the exposed API.
+	 * <p>
+	 * 	This summary is used in the following locations:
+	 * <ul class='spaced-list'>
+	 * 	<li>The value returned by {@link RestRequest#getMethodSummary()}.
+	 * 	<li>The <js>"$R{methodSummary}"</js> variable.
+	 * 	<li>The summary of the method in the Swagger page.
+	 * </ul>
+	 * <p>
+	 * 	The default value pulls the description from the <code>(className.?)[javaMethodName]</code> entry in the servlet resource bundle.
+	 * 	(e.g. <js>"MyClass.myMethod.summary = foo"</js> or <js>"myMethod.summary = foo"</js>).
+	 * <p>
+	 * 	This field value can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/summary</code>.
+	 */
+	String summary() default "";
+
+	/**
+	 * Optional description for the exposed API.
 	 * <p>
 	 * 	This description is used in the following locations:
-	 * 	<ul class='spaced-list'>
-	 * 		<li>The value returned by {@link RestRequest#getMethodDescription()}.
-	 * 		<li>The <js>"$R{methodDescription}"</js> variable.
-	 * 		<li>The description of the method in the OPTIONS page.
-	 * 	</ul>
+	 * <ul class='spaced-list'>
+	 * 	<li>The value returned by {@link RestRequest#getMethodDescription()}.
+	 * 	<li>The <js>"$R{methodDescription}"</js> variable.
+	 * 	<li>The description of the method in the Swagger page.
+	 * </ul>
 	 * <p>
 	 * 	The default value pulls the description from the <code>(className.?)[javaMethodName]</code> entry in the servlet resource bundle.
-	 * 	(e.g. <js>"MyClass.myMethod = foo"</js> or <js>"myMethod = foo"</js>).
+	 * 	(e.g. <js>"MyClass.myMethod.description = foo"</js> or <js>"myMethod.description = foo"</js>).
 	 * <p>
 	 * 	This field value can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/description</code>.
 	 */
 	String description() default "";
 
 	/**
-	 * Optional input description.
+	 * Optional external documentation information for the exposed API.
 	 * <p>
-	 * 	This annotation is provided for documentation purposes and is used to populate the method <js>"input"</js> column
-	 * 		on the OPTIONS page.
+	 * 	Used to populate the Swagger external documentation field.
 	 * <p>
-	 * Example:
+	 * 	A simplified JSON string with the following fields:
+	 * <p class='bcode'>
+	 * 	{
+	 * 		description: string,
+	 * 		url: string
+	 * 	}
+	 * </p>
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestMethod</ja>(externalDocs=<js>"{url:'http://juneau.apache.org'}"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/externalDocs</code>.
+	 */
+	String externalDocs() default "";
+
+	/**
+	 * Optional tagging information for the exposed API.
+	 * <p>
+	 * 	Used to populate the Swagger tags field.
+	 * <p>
+	 * 	A comma-delimited list of tags for API documentation control.
+	 * 	Tags can be used for logical grouping of operations by resources or any other qualifier.
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestMethod</ja>(tags=<js>"foo,bar"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/tags</code>.
+	 */
+	String tags() default "";
+
+	/**
+	 * Optional deprecated flag for the exposed API.
+	 * <p>
+	 * 	Used to populate the Swagger deprecated field.
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestMethod</ja>(deprecated=<jk>true</jk>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/deprecated</code>.
+	 */
+	boolean deprecated() default false;
+
+	/**
+	 * Optional parameter descriptions.
+	 * <p>
+	 * 	This annotation is provided for documentation purposes and is used to populate the method <js>"parameters"</js> column
+	 * 		on the Swagger page.
+	 * <p>
+	 * 	Example:
 	 * <p class='bcode'>
 	 * 	<ja>@RestMethod</ja>(
 	 * 		name=<js>"POST"</js>, path=<js>"/{a}"</js>,
 	 * 		description=<js>"This is my method."</js>,
-	 * 		input={
-	 * 			<ja>@Var</ja>(category=<js>"attr"</js>, name=<js>"a"</js>, description=<js>"The 'a' attribute"</js>),
-	 * 			<ja>@Var</ja>(category=<js>"param"</js>, name=<js>"b"</js>, description=<js>"The 'b' parameter"</js>),
-	 * 			<ja>@Var</ja>(category=<js>"content"</js>, description=<js>"The HTTP content"</js>),
-	 * 			<ja>@Var</ja>(category=<js>"header"</js>, name=<js>"D"</js>, description=<js>"The 'D' header"</js>),
-	 * 			<ja>@Var</ja>(category=<js>"foo"</js>, name=<js>"bar"</js>, description=<js>"An arbitrary category"</js>)
+	 * 		parameters={
+	 * 			<ja>@Var</ja>(in=<js>"path"</js>, name=<js>"a"</js>, description=<js>"The 'a' attribute"</js>),
+	 * 			<ja>@Var</ja>(in=<js>"query"</js>, name=<js>"b"</js>, description=<js>"The 'b' parameter"</js>, required=<jk>true</jk>),
+	 * 			<ja>@Var</ja>(in=<js>"body"</js>, description=<js>"The HTTP content"</js>),
+	 * 			<ja>@Var</ja>(in=<js>"header"</js>, name=<js>"D"</js>, description=<js>"The 'D' header"</js>),
 	 * 		}
 	 * 	)
 	 * </p>
-	 * This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in this case
-	 * the strings are internationalized.
+	 * 	This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in this case
+	 * 	the strings are internationalized.
 	 * <p class='bcode'>
 	 * 	<jk>MyClass.myMethod</jk> = <js>This is my method.</js>
-	 * 	<jk>MyClass.myMethod.req.attr.a</jk> = <js>The 'a' attribute</js>
-	 * 	<jk>MyClass.myMethod.req.param.b</jk> = <js>The 'b' parameter</js>
-	 * 	<jk>MyClass.myMethod.req.content</jk> = <js>The HTTP content</js>
-	 * 	<jk>MyClass.myMethod.req.header.d</jk> = <js>The 'D' header</js>
-	 * 	<jk>MyClass.myMethod.req.foo.bar</jk> = <js>An arbitrary category</js>
+	 * 	<jk>MyClass.myMethod.parameters.path.a.description</jk> = <js>The 'a' attribute</js>
+	 * 	<jk>MyClass.myMethod.parameters.query.b.description</jk> = <js>The 'b' parameter</js>
+	 * 	<jk>MyClass.myMethod.parameters.body.description</jk> = <js>The HTTP content</js>
+	 * 	<jk>MyClass.myMethod.parameters.header.d.description</jk> = <js>The 'D' header</js>
 	 * <p>
-	 * As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support English),
-	 * and use resource bundles if you need to support localization.
+	 * 	As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support English),
+	 * 	and use resource bundles if you need to support localization.
 	 * <p>
 	 * 	These annotations can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/paths/{path}/{method}/parameters</code>.
 	 */
-	Var[] input() default {};
-
+	Var[] parameters() default {};
 
 	/**
 	 * Optional output description.
 	 * <p>
 	 * 	This annotation is provided for documentation purposes and is used to populate the method <js>"responses"</js> column
-	 * 		on the OPTIONS page.
+	 * 		on the Swagger page.
 	 * <p>
-	 * Example:
+	 * 	Example:
 	 * <p class='bcode'>
 	 * 	<ja>@RestMethod</ja>(
 	 * 		name=<js>"GET"</js>, path=<js>"/"</js>,
@@ -369,15 +428,15 @@ public @interface RestMethod {
 	 * 		}
 	 * 	)
 	 * </p>
-	 * This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in this case
-	 * the strings are internationalized.
+	 * 	This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in this case
+	 * 	the strings are internationalized.
 	 * <p class='bcode'>
 	 * 	<jk>MyClass.myMethod.res.200</jk> = <js>OK</js>
 	 * 	<jk>MyClass.myMethod.res.302</jk> = <js>Thing wasn't found here</js>
 	 * 	<jk>MyClass.myMethod.res.302.header.Location</jk> = <js>The place to find the thing</js>
 	 * <p>
-	 * As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support English),
-	 * and use resource bundles if you need to support localization.
+	 * 	As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support English),
+	 * 	and use resource bundles if you need to support localization.
 	 * <p>
 	 * 	These annotations can contain variables (e.g. "$L{my.localized.variable}").
 	 */

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestResource.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestResource.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestResource.java
index 0279d9b..a2fa54a 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestResource.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/RestResource.java
@@ -46,18 +46,17 @@ public @interface RestResource {
 	/**
 	 * Identifies the location of the resource bundle for this class.
 	 * <p>
-	 * This annotation is used to provide localized messages for the following methods:
+	 * 	This annotation is used to provide localized messages for the following methods:
 	 * <ul>
 	 * 	<li>{@link RestServlet#getMessage(java.util.Locale, String, Object...)}
-	 * 	<li>{@link RestServlet#getMethodDescriptions(RestRequest)}
-	 * 	<li>{@link RestServlet#getLabel(RestRequest)}
+	 * 	<li>{@link RestServlet#getTitle(RestRequest)}
 	 * 	<li>{@link RestServlet#getDescription(RestRequest)}
 	 * </ul>
 	 * <p>
-	 * Refer to the {@link MessageBundle} class for a description of the message key formats
+	 * 	Refer to the {@link MessageBundle} class for a description of the message key formats
 	 * 	used in the properties file.
 	 * <p>
-	 * The value can be a relative path like <js>"nls/Messages"</js>, indicating to look for the
+	 * 	The value can be a relative path like <js>"nls/Messages"</js>, indicating to look for the
 	 * 	resource bundle <js>"com.ibm.sample.nls.Messages"</js> if the resource class
 	 * 	is in <js>"com.ibm.sample"</js>, or it can be an absolute path, like <js>"com.ibm.sample.nls.Messages"</js>
 	 */
@@ -66,11 +65,11 @@ public @interface RestResource {
 	/**
 	 * Class-level guards.
 	 * <p>
-	 * Associates one or more {@link RestGuard RestGuards} with all REST methods defined
+	 * 	Associates one or more {@link RestGuard RestGuards} with all REST methods defined
 	 * 	in this class.
-	 * These guards get called immediately before execution of any REST method in this class.
+	 * 	These guards get called immediately before execution of any REST method in this class.
 	 * <p>
-	 * Typically, guards will be used for permissions checking on the user making the request,
+	 * 	Typically, guards will be used for permissions checking on the user making the request,
 	 * 	but it can also be used for other purposes like pre-call validation of a request.
 	 */
 	Class<? extends RestGuard>[] guards() default {};
@@ -78,28 +77,28 @@ public @interface RestResource {
 	/**
 	 * Class-level converters.
 	 * <p>
-	 * Associates one or more {@link RestConverter converters} with a resource class.
-	 * These converters get called immediately after execution of the REST method in the same
+	 * 	Associates one or more {@link RestConverter converters} with a resource class.
+	 * 	These converters get called immediately after execution of the REST method in the same
 	 * 	order specified in the annotation.
 	 * <p>
-	 * Can be used for performing post-processing on the response object before serialization.
+	 * 	Can be used for performing post-processing on the response object before serialization.
 	 * <p>
-	 * Default converter implementations are provided in the {@link org.apache.juneau.server.converters} package.
+	 * 	Default converter implementations are provided in the {@link org.apache.juneau.server.converters} package.
 	 */
 	Class<? extends RestConverter>[] converters() default {};
 
 	/**
 	 * Class-level bean filters.
 	 * <p>
-	 * Shortcut to add bean filters to the bean contexts of the objects returned by the following methods:
+	 * 	Shortcut to add bean filters to the bean contexts of the objects returned by the following methods:
 	 * <ul>
 	 * 	<li>{@link RestServlet#getBeanContext()}
 	 * 	<li>{@link RestServlet#getSerializers()}
 	 * 	<li>{@link RestServlet#getParsers()}
 	 * </ul>
 	 * <p>
-	 * If the specified class is an instance of {@link BeanFilterBuilder}, then a filter built from that builder is added.
-	 * Any other classes are wrapped in a {@link InterfaceBeanFilterBuilder} to indicate that subclasses should
+	 * 	If the specified class is an instance of {@link BeanFilterBuilder}, then a filter built from that builder is added.
+	 * 	Any other classes are wrapped in a {@link InterfaceBeanFilterBuilder} to indicate that subclasses should
 	 * 	be treated as the specified class type.
 	 */
 	Class<?>[] beanFilters() default {};
@@ -107,15 +106,15 @@ public @interface RestResource {
 	/**
 	 * Class-level POJO swaps.
 	 * <p>
-	 * Shortcut to add POJO swaps to the bean contexts of the objects returned by the following methods:
+	 * 	Shortcut to add POJO swaps to the bean contexts of the objects returned by the following methods:
 	 * <ul>
 	 * 	<li>{@link RestServlet#getBeanContext()}
 	 * 	<li>{@link RestServlet#getSerializers()}
 	 * 	<li>{@link RestServlet#getParsers()}
 	 * </ul>
 	 * <p>
-	 * If the specified class is an instance of {@link PojoSwap}, then that swap is added.
-	 * Any other classes are wrapped in a {@link SurrogateSwap}.
+	 * 	If the specified class is an instance of {@link PojoSwap}, then that swap is added.
+	 * 	Any other classes are wrapped in a {@link SurrogateSwap}.
 	 */
 	Class<?>[] pojoSwaps() default {};
 
@@ -143,9 +142,9 @@ public @interface RestResource {
 	 * 	<li>{@link XmlParserContext}
 	 * </ul>
 	 * <p>
-	 * Property values will be converted to the appropriate type.
+	 * 	Property values will be converted to the appropriate type.
 	 * <p>
-	 * In some cases, properties can be overridden at runtime through the {@link RestResponse#setProperty(String, Object)} method
+	 * 	In some cases, properties can be overridden at runtime through the {@link RestResponse#setProperty(String, Object)} method
 	 * 	or through a {@link Properties @Properties} annotated method parameter.
 	 */
 	Property[] properties() default {};
@@ -153,14 +152,14 @@ public @interface RestResource {
 	/**
 	 * Specifies a list of {@link Serializer} classes to add to the list of serializers available for this servlet.
 	 * <p>
-	 * This annotation can only be used on {@link Serializer} classes that have no-arg constructors.
+	 * 	This annotation can only be used on {@link Serializer} classes that have no-arg constructors.
 	 */
 	Class<? extends Serializer>[] serializers() default {};
 
 	/**
 	 * Specifies a list of {@link Parser} classes to add to the list of parsers available for this servlet.
 	 * <p>
-	 * This annotation can only be used on {@link Parser} classes that have no-arg constructors.
+	 * 	This annotation can only be used on {@link Parser} classes that have no-arg constructors.
 	 */
 	Class<? extends Parser>[] parsers() default {};
 
@@ -168,16 +167,17 @@ public @interface RestResource {
 	 * Specifies a list of {@link ResponseHandler} classes that know how to convert POJOs returned
 	 * 	by REST methods or set via {@link RestResponse#setOutput(Object)} into appropriate
 	 * 	HTTP responses.
-	 * See {@link ResponseHandler} for details.
+	 * <p>
+	 * 	See {@link ResponseHandler} for details.
 	 */
 	Class<? extends ResponseHandler>[] responseHandlers() default {};
 
 	/**
 	 * Specifies a list of {@link Encoder} to associate with this servlet.
 	 * <p>
-	 * These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
+	 * 	These can be used to enable various kinds of compression (e.g. <js>"gzip"</js>) on requests and responses.
 	 * <p>
-	 * This annotation can only be used on {@link Encoder} classes that have no-arg constructors.
+	 * 	This annotation can only be used on {@link Encoder} classes that have no-arg constructors.
 	 *
 	 * <dl>
 	 * 	<dt>Example:</dt>
@@ -197,14 +197,14 @@ public @interface RestResource {
 	/**
 	 * Specifies default values for request headers.
 	 * <p>
-	 * Strings are of the format <js>"Header-Name: header-value"</js>.
+	 * 	Strings are of the format <js>"Header-Name: header-value"</js>.
 	 * <p>
-	 * Affects values returned by {@link RestRequest#getHeader(String)} when the header is not present on the request.
+	 * 	Affects values returned by {@link RestRequest#getHeader(String)} when the header is not present on the request.
 	 * <p>
-	 * The most useful reason for this annotation is to provide a default <code>Accept</code> header when one is not specified
+	 * 	The most useful reason for this annotation is to provide a default <code>Accept</code> header when one is not specified
 	 * 	so that a particular default {@link Serializer} is picked.
 	 * <p>
-	 * Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
+	 * 	Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
 	 *
 	 * <dl>
 	 * 	<dt>Example:</dt>
@@ -224,13 +224,13 @@ public @interface RestResource {
 	/**
 	 * Specifies default values for response headers.
 	 * <p>
-	 * Strings are of the format <js>"Header-Name: header-value"</js>.
+	 * 	Strings are of the format <js>"Header-Name: header-value"</js>.
 	 * <p>
-	 * This is equivalent to calling {@link RestResponse#setHeader(String, String)} programmatically in each of the Java methods.
+	 * 	This is equivalent to calling {@link RestResponse#setHeader(String, String)} programmatically in each of the Java methods.
 	 * <p>
-	 * The header value will not be set if the header value has already been specified (hence the 'default' in the name).
+	 * 	The header value will not be set if the header value has already been specified (hence the 'default' in the name).
 	 * <p>
-	 * Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
+	 * 	Only one header value can be specified per entry (i.e. it's not a delimited list of header entries).
 	 *
 	 * <dl>
 	 * 	<dt>Example:</dt>
@@ -250,17 +250,17 @@ public @interface RestResource {
 	/**
 	 * Defines children of this resource.
 	 * <p>
-	 * A REST child resource is simply another servlet that is initialized as part of the parent
+	 * 	A REST child resource is simply another servlet that is initialized as part of the parent
 	 * 	resource and has a servlet path directly under the parent servlet path.
-	 * The main advantage to defining servlets as REST children is that you do not need
+	 * 	The main advantage to defining servlets as REST children is that you do not need
 	 * 	to define them in the <code>web.xml</code> file of the web application.
-	 * This can cut down on the number of entries that show up in the <code>web.xml</code> file
+	 * 	This can cut down on the number of entries that show up in the <code>web.xml</code> file
 	 * 	if you are defining large numbers of servlets.
 	 * <p>
-	 * Child resources must specify a value for {@link #path()} that identifies the subpath of the
+	 * 	Child resources must specify a value for {@link #path()} that identifies the subpath of the
 	 * 	child resource relative to the parent path.
 	 * <p>
-	 * It should be noted that servlets can be nested arbitrarily deep using this technique (i.e. children can also have children).
+	 * 	It should be noted that servlets can be nested arbitrarily deep using this technique (i.e. children can also have children).
 	 *
 	 * <dl>
 	 * 	<dt>Servlet initialization:</dt>
@@ -290,35 +290,176 @@ public @interface RestResource {
 	/**
 	 * Identifies the URL subpath relative to the parent resource.
 	 * <p>
-	 * Typically, this annotation is only applicable to resources defined as children through the {@link #children()}
+	 * 	Typically, this annotation is only applicable to resources defined as children through the {@link #children()}
 	 * 	annotation.  However, it may be used in other ways (e.g. defining paths for top-level resources in microservices).
 	 * <p>
-	 * This annotation is ignored on top-level servlets (i.e. servlets defined in <code>web.xml</code> files).
-	 * Therefore, implementers can optionally specify a path value for documentation purposes.
+	 * 	This annotation is ignored on top-level servlets (i.e. servlets defined in <code>web.xml</code> files).
+	 * 	Therefore, implementers can optionally specify a path value for documentation purposes.
 	 */
 	String path() default "";
 
 	/**
-	 * Optional servlet label.
+	 * Optional servlet title.
+	 * <p>
+	 * 	It is used to populate the Swagger title field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getTitle(RestRequest)} method.
 	 * <p>
 	 * 	The default value pulls the label from the <code>label</code> entry in the servlet resource bundle.
 	 * 	(e.g. <js>"label = foo"</js> or <js>"MyServlet.label = foo"</js>).
 	 * <p>
 	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/title</code>.
 	 */
-	String label() default "";
+	String title() default "";
 
 	/**
 	 * Optional servlet description.
 	 * <p>
+	 * 	It is used to populate the Swagger description field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getDescription(RestRequest)} method.
+	 * <p>
 	 * 	The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
 	 * 	(e.g. <js>"description = foo"</js> or <js>"MyServlet.description = foo"</js>).
 	 * <p>
 	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/description</code>.
 	 */
 	String description() default "";
 
 	/**
+	 * Optional servlet terms-of-service for this API.
+	 * <p>
+	 * 	It is used to populate the Swagger terms-of-service field.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getTermsOfService(RestRequest)} method.
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/termsOfService</code>.
+	 */
+	String termsOfService() default "";
+
+	/**
+	 * Optional contact information for the exposed API.
+	 * <p>
+	 * 	It is used to populate the Swagger contact field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getContact(RestRequest)} method.
+	 * <p>
+	 * 	A simplified JSON string with the following fields:
+	 * <p class='bcode'>
+	 * 	{
+	 * 		name: string,
+	 * 		url: string,
+	 * 		email: string
+	 * 	}
+	 * </p>
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestResource</ja>(contact=<js>"{name:'John Smith',email:'john.smith@foo.bar'}"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/contact</code>.
+	 */
+	String contact() default "";
+
+	/**
+	 * Optional license information for the exposed API.
+	 * <p>
+	 * 	It is used to populate the Swagger license field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getLicense(RestRequest)} method.
+	 * <p>
+	 * 	A simplified JSON string with the following fields:
+	 * <p class='bcode'>
+	 * 	{
+	 * 		name: string,
+	 * 		url: string
+	 * 	}
+	 * </p>
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestResource</ja>(license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/license</code>.
+	 */
+	String license() default "";
+
+	/**
+	 * Provides the version of the application API (not to be confused with the specification version).
+	 * <p>
+	 * 	It is used to populate the Swagger version field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getVersion(RestRequest)} method.
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/info/version</code>.
+	 */
+	String version() default "";
+
+	/**
+	 * Optional tagging information for the exposed API.
+	 * <p>
+	 * 	It is used to populate the Swagger tags field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getTags(RestRequest)} method.
+	 * <p>
+	 *		A simplified JSON string with the following fields:
+	 * <p class='bcode'>
+	 * 	[
+	 * 		{
+	 * 			name: string,
+	 * 			description: string,
+	 * 			externalDocs: {
+	 * 				description: string,
+	 * 				url: string
+	 * 			}
+	 * 		}
+	 * 	]
+	 * </p>
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestResource</ja>(tags=<js>"[{name:'Foo',description:'Foobar'}]"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/tags</code>.
+	 */
+	String tags() default "";
+
+	/**
+	 * Optional external documentation information for the exposed API.
+	 * <p>
+	 * 	It is used to populate the Swagger external documentation field and to display on HTML pages.
+	 * 	This value can be retrieved programmatically through the {@link RestServlet#getExternalDocs(RestRequest)} method.
+	 * <p>
+	 * 	A simplified JSON string with the following fields:
+	 * <p class='bcode'>
+	 * 	{
+	 * 		description: string,
+	 * 		url: string
+	 * 	}
+	 * </p>
+	 * <p>
+	 * 	Example:
+	 * <p class='bcode'>
+	 * 	<ja>@RestResource</ja>(externalDocs=<js>"{url:'http://juneau.apache.org'}"</js>)
+	 * </p>
+	 * <p>
+	 * 	This field can contain variables (e.g. "$L{my.localized.variable}").
+	 * <p>
+	 * 	Corresponds to the swagger field <code>/tags</code>.
+	 */
+	String externalDocs() default "";
+
+	/**
 	 * Optional location of configuration file for this servlet.
 	 * <p>
 	 * 	The configuration file .
@@ -334,10 +475,10 @@ public @interface RestResource {
 	 * 	The resulting stylesheet becomes available through the servlet via the URL <js>"[servletpath]/style.css"</js>.
 	 * <p>
 	 * 	The default set of styles located in the <code>org.apache.juneau.server.styles</code> package are:
-	 * <ul class='spaced-list'>
-	 * 	<li><js>"styles/juneau.css"</js> - Theme based on Jazz look-and-feel.
-	 * 	<li><js>"styles/devops.css"</js> - Theme based on IBM DevOps look-and-feel.
-	 * </ul>
+	 * 	<ul class='spaced-list'>
+	 * 		<li><js>"styles/juneau.css"</js> - Theme based on Jazz look-and-feel.
+	 * 		<li><js>"styles/devops.css"</js> - Theme based on IBM DevOps look-and-feel.
+	 * 	</ul>
 	 * <p>
 	 * 	The classpath search starts with the child servlet class and proceeds up the class hierarchy
 	 * 	chain.  Since the {@link RestServlet} class is in the <code>org.apache.juneau.server</code> package
@@ -456,5 +597,4 @@ public @interface RestResource {
 	 * 	If not specified, uses <js>"X-Client-Version"</js>.
 	 */
 	String clientVersionHeader() default "";
-
 }

http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/7f2bcfdd/juneau-server/src/main/java/org/apache/juneau/server/annotation/Var.java
----------------------------------------------------------------------
diff --git a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Var.java b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Var.java
index 6a8e90c..f3c3376 100755
--- a/juneau-server/src/main/java/org/apache/juneau/server/annotation/Var.java
+++ b/juneau-server/src/main/java/org/apache/juneau/server/annotation/Var.java
@@ -18,22 +18,15 @@ import static java.lang.annotation.RetentionPolicy.*;
 import java.lang.annotation.*;
 
 /**
- * Annotation used in conjunction with {@link RestMethod#input()} and {@link Response#output()} to identify content and header descriptions
- * 	on specific method responses.
+ * Annotation used in conjunction with {@link RestMethod#parameters()} to identify content and header descriptions
+ * 	on specific method requests.
  *
  * <h6 class='topic'>Example</h6>
  * <p class='bcode'>
  * 	<ja>@RestMethod</ja>(
  * 		name=<js>"*"</js>,
- * 		requestVars={
- * 				<ja>@Var</ja>(category=<js>"header"</js>,name=<js>"Range"</js>,description=<js>"$L{ContentRange.description}"</js>)
- * 		}
- * 		responses={
- * 			<ja>@Response</ja>(code=200,description=<js>"Everything was great."</js>,
- * 				responseVars={
- * 					<ja>@Var</ja>(category=<js>"header"</js>,name=<js>"Content-Range"</js>,description=<js>"$L{ContentRange.description}"</js>)
- * 				})
- * 			<ja>@Response</ja>(code=404,description=<js>"File was not found."</js>)
+ * 		parameters={
+ * 			<ja>@Var</ja>(in=<js>"header"</js>, name=<js>"Range"</js>, description=<js>"$L{ContentRange.description}"</js>)
  * 		}
  * 	)
  * 	<jk>public void</jk> doAnything(RestRequest req, RestResponse res, <ja>@Method</ja> String method) {
@@ -50,21 +43,108 @@ import java.lang.annotation.*;
 public @interface Var {
 
 	/**
-	 * Variable category (e.g. <js>"header"</js>, <js>"content"</js>).
-	 * The {@link VarCategory} class contains predefined constants.
+	 * The location of the parameter.
+	 * <p>
+	 * Possible values are:
+	 * <ul>
+	 * 	<li><js>"query"</js>
+	 * 	<li><js>"header"</js>
+	 * 	<li><js>"path"</js>
+	 * 	<li><js>"formData"</js>
+	 * 	<li><js>"body"</js>
+	 * </ul>
 	 */
-	String category();
+	String in() default "";
 
 	/**
-	 * Variable name (e.g. <js>"Content-Range"</js>).
+	 * The name of the parameter (e.g. <js>"Content-Range"</js>).
+	 * <p>
+	 * Var names are case sensitive.
+	 * If <code>in</code> is <js>"path"</js>, the name field MUST correspond to the associated path segment from the <code>path</code> field in the <a href='http://swagger.io/specification/#pathsObject'>Paths Object</a>.
+	 * See <a href='http://swagger.io/specification/#pathTemplating'>Path Templating</a> for further information.
+	 * For all other cases, the name corresponds to the parameter name used based on the <code>in</code> property.
 	 */
 	String name() default "";
 
 	/**
-	 * Variable description (e.g. <js>"Indicates the range returned when Range header is present in the request"</js>).
+	 * Var description (e.g. <js>"Indicates the range returned when Range header is present in the request"</js>).
 	 * <p>
-	 * 	The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
-	 * 	(e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>).
+	 * A brief description of the parameter.
+	 * This could contain examples of use.
+	 * <a href='https://help.github.com/articles/github-flavored-markdown'>GFM syntax</a> can be used for rich text representation.
+	 * <p>
+	 * The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
+	 * (e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>).
 	 */
 	String description() default "";
+
+	/**
+	 * Determines whether this parameter is mandatory.
+	 * <p>
+	 * If the parameter is <code>in</code> <js>"path"</js>, this property is required and its value MUST be <jk>true</jk>.
+	 * Otherwise, the property MAY be included and its default value is <jk>false</jk>.
+	 */
+	boolean required() default false;
+
+	/**
+	 * The schema defining the type used for the body parameter.
+	 * <p>
+	 * Only applicable for <code>in</code> of type <js>"body"</js>.
+	 * <p>
+	 * The schema is a JSON object specified <a href='http://swagger.io/specification/#schemaObject'>here</a>.
+	 */
+	String schema() default "";
+
+	/**
+	 * The type of the parameter.
+	 */
+	String type() default "string";
+
+	/**
+	 * The extending format for the previously mentioned <code>type</code>.
+	 * <p>
+	 * See <a href='http://swagger.io/specification/#dataTypeFormat'>Data Type Formats</a> for further details.
+	 */
+	String format() default "";
+
+	/**
+	 * Sets the ability to pass empty-valued parameters.
+	 * <p>
+	 * This is valid only for either <code>query</code> or <code>formData</code> parameters and allows you to send a parameter with a name only or an empty value.
+	 * Default value is <jk>false</jk>.
+	 */
+	boolean allowEmptyValue() default false;
+
+	/**
+	 * Required if <code>type</code> is <js>"array"</js>.
+	 * <p>
+	 * Describes the type of items in the array.
+	 */
+	String items() default "";
+
+	/**
+	 * Determines the format of the array if type array is used.
+	 * <p>
+	 * Possible values are:
+	 * <ul>
+	 * 	<li><js>"csv"</js> - comma separated values <js>"foo,bar"</js>.
+	 * 	<li><js>"ssv"</js> - space separated values <js>"foo bar"</js>.
+	 * 	<li><js>"tsv"</js> - tab separated values <js>"foo\tbar"</js>.
+	 * 	<li><js>"pipes"</js> - pipe separated values <js>"foo|bar"</js>.
+	 * 	<li><js>"multi"</js> - corresponds to multiple parameter instances instead of multiple values for a single instance <js>"foo=bar&foo=baz"</js>.
+	 * 		This is valid only for parameters <code>in</code> <js>"query"</js> or <js>"formData"</js>.
+	 * </ul>
+	 * Default value is <js>"csv"</js>.
+	 */
+	String collectionFormat() default "";
+
+	/**
+	 * Declares the value of the parameter that the server will use if none is provided.
+	 * <p>
+	 * For example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request.
+	 * (Note: "default" has no meaning for required parameters.)
+	 * See <a href='http://json-schema.org/latest/json-schema-validation.html#anchor101'>http://json-schema.org/latest/json-schema-validation.html#anchor101</a>.
+	 * Unlike JSON Schema this value MUST conform to the defined <code>type</code> for this parameter.
+	 */
+	String _default() default "";
 }


Mime
View raw message