You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/06/07 00:27:45 UTC
[2/5] incubator-juneau git commit: Enhancements to HTML Doc rendering.
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
index 50f25f6..725387a 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestResponse.java
@@ -424,65 +424,358 @@ public final class RestResponse extends HttpServletResponseWrapper {
}
/**
- * Sets the page title for HTML views.
+ * Sets the HTML page title.
* <p>
- * This is the programmatic equivalent to the {@link RestResource#pageTitle() @RestResource#pageTitle()}/
- * {@link RestMethod#pageTitle() @RestMethod#pageTitle()} annotations.
+ * The format of this value is plain text.
+ * <p>
+ * It gets wrapped in a <code><xt><h3> <xa>class</xa>=<xs>'title'</xs>></xt></code> element and then added
+ * to the <code><xt><header></code> section on the page.
+ * <p>
+ * If not specified, the page title is pulled from one of the following locations:
+ * <ol>
+ * <li><code>{servletClass}.{methodName}.pageTitle</code> resource bundle value.
+ * <li><code>{servletClass}.pageTitle</code> resource bundle value.
+ * <li><code><ja>@RestResource</ja>(title)</code> annotation.
+ * <li><code>{servletClass}.title</code> resource bundle value.
+ * <li><code>info/title</code> entry in swagger file.
+ * <ol>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
* <p>
- * This is a shortcut for calling <code>setProperty(<jsf>HTMLDOC_title</jsf>, title);</code>
* <ul class='doctree'>
* <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate a page title with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
+ * In most cases, you'll simply want to use the <code>@RestResource(title)</code> annotation to specify the
+ * page title.
+ * However, this annotation is provided in cases where you want the page title to be different that the one
+ * shown in the swagger document.
* </ul>
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#title() @HtmlDoc.title()} annotation.
*
- * @param title The localized page title to render on the page.
- * Object will be converted to a string using {@link Object#toString()}.
+ * @param value The HTML page title.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
- public RestResponse setPageTitle(Object title) {
- return setProperty(HtmlDocSerializerContext.HTMLDOC_title, title);
+ public RestResponse setHtmlTitle(Object value) {
+ return setProperty(HtmlDocSerializerContext.HTMLDOC_title, value);
}
/**
- * Sets the page text for HTML views.
+ * Sets the HTML page description.
+ * <p>
+ * The format of this value is plain text.
+ * <p>
+ * It gets wrapped in a <code><xt><h5> <xa>class</xa>=<xs>'description'</xs>></xt></code> element and then
+ * added to the <code><xt><header></code> section on the page.
+ * <p>
+ * If not specified, the page title is pulled from one of the following locations:
+ * <ol>
+ * <li><code>{servletClass}.{methodName}.pageText</code> resource bundle value.
+ * <li><code>{servletClass}.pageText</code> resource bundle value.
+ * <li><code><ja>@RestMethod</ja>(summary)</code> annotation.
+ * <li><code>{servletClass}.{methodName}.summary</code> resource bundle value.
+ * <li><code>summary</code> entry in swagger file for method.
+ * <li><code>{servletClass}.description</code> resource bundle value.
+ * <li><code>info/description</code> entry in swagger file.
+ * <ol>
* <p>
- * This is the programmatic equivalent to the {@link RestResource#pageText() @RestResource#pageText()}/
- * {@link RestMethod#pageText() @RestMethod#pageText()} annotations.
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
* <p>
- * This is a shortcut for calling <code>setProperty(<jsf>HTMLDOC_text</jsf>, text);</code>
* <ul class='doctree'>
* <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate page text with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
+ * In most cases, you'll simply want to use the <code>@RestResource(description)</code> or
+ * <code>@RestMethod(summary)</code> annotations to specify the page text.
+ * However, this annotation is provided in cases where you want the text to be different that the values shown
+ * in the swagger document.
* </ul>
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#description() @HtmlDoc.description()} annotation.
*
- * @param text The localized page text to render on the page.
+ * @param value The HTML page description.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
* @return This object (for method chaining).
*/
- public RestResponse setPageText(Object text) {
- return setProperty(HtmlDocSerializerContext.HTMLDOC_text, text);
+ public RestResponse setHtmlDescription(Object value) {
+ return setProperty(HtmlDocSerializerContext.HTMLDOC_description, value);
}
/**
- * Sets the page text for HTML views.
+ * Sets the HTML header section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The page header normally contains the title and description, but this value can be used to override the contents
+ * to be whatever you want.
* <p>
- * This is the programmatic equivalent to the {@link RestResource#pageLinks() @RestResource#pageLinks()}/
- * {@link RestMethod#pageLinks() @RestMethod#pageLinks()} annotations.
+ * When a value is specified, the {@link #setHtmlTitle(Object)} and {@link #setHtmlDescription(Object)} values will be ignored.
* <p>
- * This is a shortcut for calling <code>setProperty(<jsf>HTMLDOC_links</jsf>, links);</code>
+ * A value of <js>"NONE"</js> can be used to force no header.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#header() @HtmlDoc.header()} annotation.
*
- * <ul class='doctree'>
- * <li class='info'>
- * <b>Tip:</b> Use {@link StringMessage} to generate page links with delayed serialization so as not to
- * waste string concatenation cycles on non-HTML views.
- * </ul>
+ * @param value The HTML header section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlHeader(Object value) {
+ return setProperty(HtmlDocSerializerContext.HTMLDOC_title, value);
+ }
+
+ /**
+ * Sets the links in the HTML nav section.
+ * <p>
+ * The format of this value is a lax-JSON map of key/value pairs where the keys are the link text and the values are
+ * relative (to the servlet) or absolute URLs.
+ * <p>
+ * The page links are positioned immediately under the title and text.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This field can also use URIs of any support type in {@link UriResolver}.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#links() @HtmlDoc.links()} annotation.
+ *
+ * @param value The HTML nav section links links.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlLinks(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_links, value);
+ return this;
+ }
+
+ /**
+ * Sets the HTML nav section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The nav section of the page contains the links.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * When a value is specified, the {@link #setHtmlLinks(Object)} value will be ignored.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#nav() @HtmlDoc.nav()} annotation.
+ *
+ * @param value The HTML nav section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlNav(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_nav, value);
+ return this;
+ }
+
+ /**
+ * Sets the HTML aside section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The aside section typically floats on the right side of the page.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#aside() @HtmlDoc.aside()} annotation.
+ *
+ * @param value The HTML aside section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlAside(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_aside, value);
+ return this;
+ }
+
+ /**
+ * Sets the HTML footer section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The footer section typically floats on the bottom of the page.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#footer() @HtmlDoc.footer()} annotation.
+ *
+ * @param value The HTML footer section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlFooter(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_footer, value);
+ return this;
+ }
+
+ /**
+ * Sets the HTML CSS style section contents.
+ * <p>
+ * The format of this value is CSS.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#css() @HtmlDoc.css()} annotation.
+ *
+ * @param value The HTML CSS style section contents.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlCss(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_css, value);
+ return this;
+ }
+
+ /**
+ * Sets the CSS URL in the HTML CSS style section.
+ * <p>
+ * The format of this value is a URL.
+ * <p>
+ * Specifies the URL to the stylesheet to add as a link in the style tag in the header.
+ * <p>
+ * The format of this value is CSS.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>) and can use URL protocols defined
+ * by {@link UriResolver}.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#cssUrl() @HtmlDoc.cssUrl()} annotation.
+ *
+ * @param value The CSS URL in the HTML CSS style section.
+ * Object will be converted to a string using {@link Object#toString()}.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * <b>Tip:</b> Use {@link StringMessage} to generate value with delayed serialization so as not to
+ * waste string concatenation cycles on non-HTML views.
+ * </ul>
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlCssUrl(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_cssUrl, value);
+ return this;
+ }
+
+ /**
+ * Shorthand method for forcing the rendered HTML content to be no-wrap.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#nowrap() @HtmlDoc.nowrap()} annotation.
+ *
+ * @param value The new nowrap setting.
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlNoWrap(boolean value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_nowrap, value);
+ return this;
+ }
+
+ /**
+ * Specifies the text to display when serializing an empty array or collection.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#noResultsMessage() @HtmlDoc.noResultsMessage()} annotation.
+ *
+ * @param value The text to display when serializing an empty array or collection.
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlNoResultsMessage(Object value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_noResultsMessage, value);
+ return this;
+ }
+
+ /**
+ * Specifies the template class to use for rendering the HTML page.
+ * <p>
+ * By default, uses {@link HtmlDocTemplateBasic} to render the contents, although you can provide
+ * your own custom renderer or subclasses from the basic class to have full control over how the page is
+ * rendered.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#template() @HtmlDoc.template()} annotation.
+ *
+ * @param value The HTML page template to use to render the HTML page.
+ * @return This object (for method chaining).
+ */
+ public RestResponse setHtmlTemplate(Class<? extends HtmlDocTemplate> value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_template, value);
+ return this;
+ }
+
+ /**
+ * Specifies the template class to use for rendering the HTML page.
+ * <p>
+ * By default, uses {@link HtmlDocTemplateBasic} to render the contents, although you can provide
+ * your own custom renderer or subclasses from the basic class to have full control over how the page is
+ * rendered.
+ * <p>
+ * This is the programmatic equivalent to the {@link HtmlDoc#template() @HtmlDoc.template()} annotation.
*
- * @param links The localized page links render on the page.
+ * @param value The HTML page template to use to render the HTML page.
* @return This object (for method chaining).
*/
- public RestResponse setPageLinks(Object links) {
- properties.put(HtmlDocSerializerContext.HTMLDOC_links, links);
+ public RestResponse setHtmlTemplate(HtmlDocTemplate value) {
+ properties.put(HtmlDocSerializerContext.HTMLDOC_template, value);
return this;
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
index 51252b2..050ad0e 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/RestServletDefault.java
@@ -167,8 +167,7 @@ import org.apache.juneau.xml.*;
UrlEncodingSerializer.class,
MsgPackSerializer.class,
SoapXmlSerializer.class,
- PlainTextSerializer.class,
- JsoSerializer.class
+ PlainTextSerializer.class
},
parsers={
JsonParser.class,
@@ -197,9 +196,13 @@ public abstract class RestServletDefault extends RestServlet {
* @return A bean containing the contents for the OPTIONS page.
*/
@RestMethod(name="OPTIONS", path="/*",
- pageLinks="{back:'$R{servletURI}'}",
+ htmldoc=@HtmlDoc(
+ links="{back:'servlet:/',json:'servlet:/?method=OPTIONS&Accept=text/json&plainText=true'}",
+ description="Swagger documentation",
+ aside="NONE"
+ ),
summary="Resource options",
- description="Description of this resource"
+ description="Swagger documentation"
)
public Swagger getOptions(RestRequest req) {
return req.getSwagger();
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
new file mode 100644
index 0000000..80ddf10
--- /dev/null
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/HtmlDoc.java
@@ -0,0 +1,339 @@
+// ***************************************************************************************************************************
+// * 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 org.apache.juneau.*;
+import org.apache.juneau.html.*;
+import org.apache.juneau.rest.*;
+
+/**
+ * Contains all the configurable annotations for the {@link HtmlDocSerializer}.
+ * <p>
+ * Used with {@link RestResource#htmldoc()} and {@link RestMethod#htmldoc()} to customize the HTML view of
+ * serialized POJOs.
+ * <p>
+ * All annotations specified here have no effect on any serializers other than {@link HtmlDocSerializer} and is
+ * provided as a shorthand method of for specifying configuration properties.
+ * <p>
+ * For example, the following two methods for defining the HTML document title are considered equivalent:
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * properties={
+ * <ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>, value=<js>"My Resource Page"</js>)
+ * }
+ * )
+ *
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * title=<js>"My Resource Page"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * The purpose of these annotation is to populate the HTML document view which by default consists of the following
+ * structure:
+ * <p class='bcode'>
+ * <xt><html>
+ * <head>
+ * <style <xa>type</xa>=<xs>'text/css'</xs>>
+ * <xv>CSS styles and links to stylesheets</xv>
+ * </style>
+ * </head>
+ * <body>
+ * <header>
+ * <xv>Page title and description</xv>
+ * </header>
+ * <nav>
+ * <xv>Page links</xv>
+ * </nav>
+ * <aside>
+ * <xv>Side-bar page links</xv>
+ * </aside>
+ * <article>
+ * <xv>Contents of serialized object</xv>
+ * </article>
+ * <footer>
+ * <xv>Footer message</xv>
+ * </footer>
+ * </body>
+ * </html></xt>
+ * </p>
+ */
+public @interface HtmlDoc {
+
+ /**
+ * Sets the HTML page title.
+ * <p>
+ * The format of this value is plain text.
+ * <p>
+ * It gets wrapped in a <code><xt><h3> <xa>class</xa>=<xs>'title'</xs>></xt></code> element and then added
+ * to the <code><xt><header></code> section on the page.
+ * <p>
+ * If not specified, the page title is pulled from one of the following locations:
+ * <ol>
+ * <li><code>{servletClass}.{methodName}.pageTitle</code> resource bundle value.
+ * <li><code>{servletClass}.pageTitle</code> resource bundle value.
+ * <li><code><ja>@RestResource</ja>(title)</code> annotation.
+ * <li><code>{servletClass}.title</code> resource bundle value.
+ * <li><code>info/title</code> entry in swagger file.
+ * <ol>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * In most cases, you'll simply want to use the <code>@RestResource(title)</code> annotation to specify the
+ * page title.
+ * However, this annotation is provided in cases where you want the page title to be different that the one
+ * shown in the swagger document.
+ * </ul>
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlTitle(String)}/{@link RestResponse#setHtmlTitle(Object)} methods.
+ */
+ String title() default "";
+
+ /**
+ * Sets the HTML page description.
+ * <p>
+ * The format of this value is plain text.
+ * <p>
+ * It gets wrapped in a <code><xt><h5> <xa>class</xa>=<xs>'description'</xs>></xt></code> element and then
+ * added to the <code><xt><header></code> section on the page.
+ * <p>
+ * If not specified, the page title is pulled from one of the following locations:
+ * <ol>
+ * <li><code>{servletClass}.{methodName}.pageText</code> resource bundle value.
+ * <li><code>{servletClass}.pageText</code> resource bundle value.
+ * <li><code><ja>@RestMethod</ja>(summary)</code> annotation.
+ * <li><code>{servletClass}.{methodName}.summary</code> resource bundle value.
+ * <li><code>summary</code> entry in swagger file for method.
+ * <li><code>{servletClass}.description</code> resource bundle value.
+ * <li><code>info/description</code> entry in swagger file.
+ * <ol>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * <ul class='doctree'>
+ * <li class='info'>
+ * In most cases, you'll simply want to use the <code>@RestResource(description)</code> or
+ * <code>@RestMethod(summary)</code> annotations to specify the page text.
+ * However, this annotation is provided in cases where you want the text to be different that the values shown
+ * in the swagger document.
+ * </ul>
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlDescription(String)}/{@link RestResponse#setHtmlDescription(Object)} methods.
+ */
+ String description() default "";
+
+ /**
+ * Sets the HTML header section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The page header normally contains the title and description, but this value can be used to override the contents
+ * to be whatever you want.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * header=<js>"<p>This is my REST interface</p>"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * When a value is specified, the {@link #title()} and {@link #description()} values will be ignored.
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no header.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlHeader(String)}/{@link RestResponse#setHtmlHeader(Object)} methods.
+ */
+ String header() default "";
+
+ /**
+ * Sets the links in the HTML nav section.
+ * <p>
+ * The format of this value is a lax-JSON map of key/value pairs where the keys are the link text and the values are
+ * relative (to the servlet) or absolute URLs.
+ * <p>
+ * The page links are positioned immediately under the title and text.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * links=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * This field can also use URIs of any support type in {@link UriResolver}.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlLinks(String)}/{@link RestResponse#setHtmlLinks(Object)} methods.
+ */
+ String links() default "";
+
+ /**
+ * Sets the HTML nav section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The nav section of the page contains the links.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * nav=<js>"<p>Custom nav content</p>"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * When a value is specified, the {@link #links()} value will be ignored.
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlNav(String)}/{@link RestResponse#setHtmlNav(Object)} methods.
+ */
+ String nav() default "";
+
+ /**
+ * Sets the HTML aside section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The aside section typically floats on the right side of the page.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * aside=<js>"<p>Custom aside content</p>"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlAside(String)}/{@link RestResponse#setHtmlAside(Object)} methods.
+ */
+ String aside() default "";
+
+ /**
+ * Sets the HTML footer section contents.
+ * <p>
+ * The format of this value is HTML.
+ * <p>
+ * The footer section typically floats on the bottom of the page.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * footer=<js>"<p>Custom footer content</p>"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlFooter(String)}/{@link RestResponse#setHtmlFooter(Object)} methods.
+ */
+ String footer() default "";
+
+ /**
+ * Sets the HTML CSS style section contents.
+ * <p>
+ * The format of this value is CSS.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * css=<js>".red{color:red;}\n.blue{color:blue}"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * <p>
+ * A value of <js>"NONE"</js> can be used to force no value.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlCss(String)}/{@link RestResponse#setHtmlCss(Object)} methods.
+ */
+ String css() default "";
+
+ /**
+ * Sets the CSS URL in the HTML CSS style section.
+ * <p>
+ * The format of this value is a URL.
+ * <p>
+ * Specifies the URL to the stylesheet to add as a link in the style tag in the header.
+ * <p>
+ * The format of this value is CSS.
+ * <p>
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestResource</ja>(
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * cssUrl=<js>"http://someOtherHost/stealTheir.css"</js>
+ * )
+ * )
+ * </p>
+ * <p>
+ * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>) and can use URL protocols defined
+ * by {@link UriResolver}.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlCssUrl(String)}/{@link RestResponse#setHtmlCssUrl(Object)} methods.
+ */
+ String cssUrl() default "servlet:/style.css";
+
+ /**
+ * Shorthand method for forcing the rendered HTML content to be no-wrap.
+ */
+ boolean nowrap() default false;
+
+ /**
+ * Specifies the text to display when serializing an empty array or collection.
+ */
+ String noResultsMessage() default "no results";
+
+ /**
+ * Specifies the template class to use for rendering the HTML page.
+ * <p>
+ * By default, uses {@link HtmlDocTemplateBasic} to render the contents, although you can provide
+ * your own custom renderer or subclasses from the basic class to have full control over how the page is
+ * rendered.
+ * <p>
+ * The programmatic equivalent to this annotation are the {@link RestConfig#setHtmlTemplate(Class)}/{@link RestResponse#setHtmlTemplate(Class)} methods.
+ */
+ Class<? extends HtmlDocTemplate> template() default HtmlDocTemplate.class;
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
new file mode 100644
index 0000000..b43affe
--- /dev/null
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java
@@ -0,0 +1,161 @@
+// ***************************************************************************************************************************
+// * 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;
+
+/**
+ * Extended annotation for {@link RestMethod#swagger() RestMethod.swagger()}.
+ */
+public @interface MethodSwagger {
+
+ /**
+ * Optional external documentation information for the exposed API.
+ * <p>
+ * Used to populate the Swagger external documentation field.
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * description: string,
+ * url: string
+ * }
+ * </p>
+ * <p>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].externalDocs</code> entry in the servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js> or <js>"myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].tags</code> entry in the servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.tags = foo,bar"</js> or <js>"myMethod.tags = foo,bar"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>
+ * The default value pulls the description from the <code>(className.?)[javaMethodName].deprecated</code> entry in the servlet resource bundle.
+ * (e.g. <js>"MyClass.myMethod.deprecated = true"</js> or <js>"myMethod.deprecated = foo,bar"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"POST"</js>, path=<js>"/{a}"</js>,
+ * description=<js>"This is my method."</js>,
+ * parameters={
+ * <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"a"</js>, description=<js>"The 'a' attribute"</js>),
+ * <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"b"</js>, description=<js>"The 'b' parameter"</js>, required=<jk>true</jk>),
+ * <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The HTTP content"</js>),
+ * <ja>@Parameter</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.
+ * <p class='bcode'>
+ * <jk>MyClass.myMethod.description</jk> = <js>This is my method.</js>
+ * <jk>MyClass.myMethod.req.path.a.description</jk> = <js>The 'a' attribute</js>
+ * <jk>MyClass.myMethod.req.query.b.description</jk> = <js>The 'b' parameter</js>
+ * <jk>MyClass.myMethod.req.body.description</jk> = <js>The HTTP content</js>
+ * <jk>MyClass.myMethod.req.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.
+ * <p>
+ * These annotations can contain variables (e.g. "$L{my.localized.variable}").
+ * <p>
+ * Corresponds to the swagger field <code>/paths/{path}/{method}/parameters</code>.
+ */
+ Parameter[] 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 Swagger page.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <ja>@RestMethod</ja>(
+ * name=<js>"GET"</js>, path=<js>"/"</js>,
+ * responses={
+ * <ja>@Response</ja>(200),
+ * <ja>@Response</ja>(
+ * value=302,
+ * description=<js>"Thing wasn't found here"</js>,
+ * headers={
+ * <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The place to find the thing"</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.
+ * <p class='bcode'>
+ * <jk>MyClass.myMethod.res.200.description</jk> = <js>OK</js>
+ * <jk>MyClass.myMethod.res.302.description</jk> = <js>Thing wasn't found here</js>
+ * <jk>MyClass.myMethod.res.302.header.Location.description</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.
+ * <p>
+ * These annotations can contain variables (e.g. "$L{my.localized.variable}").
+ */
+ Response[] responses() default {};
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
index 76c7b77..26c0971 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Parameter.java
@@ -18,16 +18,18 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Annotation used in conjunction with {@link RestMethod#parameters()} to identify content and header descriptions
+ * Annotation used in conjunction with {@link MethodSwagger#parameters()} to identify content and header descriptions
* on specific method requests.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
* <ja>@RestMethod</ja>(
* name=<js>"*"</js>,
- * parameters={
- * <ja>@Parameter</ja>(in=<js>"header"</js>, name=<js>"Range"</js>, description=<js>"$L{ContentRange.description}"</js>)
- * }
+ * swagger=@MethodSwagger(
+ * parameters={
+ * <ja>@Parameter</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) {
* ...
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
new file mode 100644
index 0000000..d925bbc
--- /dev/null
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java
@@ -0,0 +1,177 @@
+// ***************************************************************************************************************************
+// * 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 org.apache.juneau.rest.*;
+
+/**
+ * Extended annotation for {@link RestResource#swagger() @RestResource.swagger()}.
+ */
+public @interface ResourceSwagger {
+ /**
+ * Optional servlet terms-of-service for this API.
+ * <p>
+ * It is used to populate the Swagger terms-of-service field.
+ * <p>
+ * The default value pulls the description from the <code>termsOfService</code> entry in the servlet resource bundle.
+ * (e.g. <js>"termsOfService = foo"</js> or <js>"MyServlet.termsOfService = foo"</js>).
+ * <p>
+ * This field can contain variables (e.g. "$L{my.localized.variable}").
+ * <p>
+ * Corresponds to the swagger field <code>/info/termsOfService</code>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTermsOfService(RestRequest)} method.
+ */
+ 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.
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * name: string,
+ * url: string,
+ * email: string
+ * }
+ * </p>
+ * <p>
+ * The default value pulls the description from the <code>contact</code> entry in the servlet resource bundle.
+ * (e.g. <js>"contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js> or <js>"MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getContact(RestRequest)} method.
+ */
+ 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.
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * name: string,
+ * url: string
+ * }
+ * </p>
+ * <p>
+ * The default value pulls the description from the <code>license</code> entry in the servlet resource bundle.
+ * (e.g. <js>"license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> or <js>"MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getLicense(RestRequest)} method.
+ */
+ 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.
+ * <p>
+ * The default value pulls the description from the <code>version</code> entry in the servlet resource bundle.
+ * (e.g. <js>"version = 2.0"</js> or <js>"MyServlet.version = 2.0"</js>).
+ * <p>
+ * This field can contain variables (e.g. "$L{my.localized.variable}").
+ * <p>
+ * Corresponds to the swagger field <code>/info/version</code>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getVersion(RestRequest)} method.
+ */
+ 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.
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * [
+ * {
+ * name: string,
+ * description: string,
+ * externalDocs: {
+ * description: string,
+ * url: string
+ * }
+ * }
+ * ]
+ * </p>
+ * <p>
+ * The default value pulls the description from the <code>tags</code> entry in the servlet resource bundle.
+ * (e.g. <js>"tags = [{name:'Foo',description:'Foobar'}]"</js> or <js>"MyServlet.tags = [{name:'Foo',description:'Foobar'}]"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTags(RestRequest)} method.
+ */
+ 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.
+ * <p>
+ * A simplified JSON string with the following fields:
+ * <p class='bcode'>
+ * {
+ * description: string,
+ * url: string
+ * }
+ * </p>
+ * <p>
+ * The default value pulls the description from the <code>externalDocs</code> entry in the servlet resource bundle.
+ * (e.g. <js>"externalDocs = {url:'http://juneau.apache.org'}"</js> or <js>"MyServlet.externalDocs = {url:'http://juneau.apache.org'}"</js>).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <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>.
+ * <p>
+ * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getExternalDocs(RestRequest)} method.
+ */
+ String externalDocs() default "";
+
+
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Response.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Response.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Response.java
index 3b72a74..1c1bd39 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Response.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/Response.java
@@ -18,17 +18,19 @@ import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
- * Annotation used in conjunction with {@link RestMethod#responses()} to identify possible responses by the method.
+ * Annotation used in conjunction with {@link MethodSwagger#responses()} to identify possible responses by the method.
*
* <h5 class='section'>Example:</h5>
* <p class='bcode'>
* <ja>@RestMethod</ja>(
* name=<js>"*"</js>,
- * responses={
- * <ja>@Response</ja>(value=200,description=<js>"Everything was great."</js>),
- * <ja>@Response</ja>(value=404,description=<js>"File was not found."</js>)
- * <ja>@Response</ja>(500),
- * }
+ * swagger=@ResourceSwagger(
+ * responses={
+ * <ja>@Response</ja>(value=200,description=<js>"Everything was great."</js>),
+ * <ja>@Response</ja>(value=404,description=<js>"File was not found."</js>)
+ * <ja>@Response</ja>(500),
+ * }
+ * )
* )
* <jk>public void</jk> doAnything(RestRequest req, RestResponse res, <ja>@Method</ja> String method) {
* ...
@@ -70,9 +72,11 @@ public @interface Response {
* <p class='bcode'>
* <ja>@RestMethod</ja>(
* name=<js>"*"</js>,
- * responses={
- * <ja>@Response</ja>(value=200,schema=<js>"{type:'string',description:'A serialized Person bean.'}"</js>),
- * }
+ * swagger=@MethodSwagger(
+ * responses={
+ * <ja>@Response</ja>(value=200,schema=<js>"{type:'string',description:'A serialized Person bean.'}"</js>),
+ * }
+ * )
* </p>
*/
String schema() default "";
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
index b2fa562..fc770a5 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java
@@ -21,6 +21,7 @@ import org.apache.juneau.encoders.*;
import org.apache.juneau.parser.*;
import org.apache.juneau.remoteable.*;
import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.widget.*;
import org.apache.juneau.serializer.*;
/**
@@ -374,147 +375,6 @@ public @interface RestMethod {
String description() default "";
/**
- * Optional external documentation information for the exposed API.
- * <p>
- * Used to populate the Swagger external documentation field.
- * <p>
- * A simplified JSON string with the following fields:
- * <p class='bcode'>
- * {
- * description: string,
- * url: string
- * }
- * </p>
- * <p>
- * The default value pulls the description from the <code>(className.?)[javaMethodName].externalDocs</code> entry in the servlet resource bundle.
- * (e.g. <js>"MyClass.myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js> or <js>"myMethod.externalDocs = {url:'http://juneau.apache.org'}"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>
- * The default value pulls the description from the <code>(className.?)[javaMethodName].tags</code> entry in the servlet resource bundle.
- * (e.g. <js>"MyClass.myMethod.tags = foo,bar"</js> or <js>"myMethod.tags = foo,bar"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>
- * The default value pulls the description from the <code>(className.?)[javaMethodName].deprecated</code> entry in the servlet resource bundle.
- * (e.g. <js>"MyClass.myMethod.deprecated = true"</js> or <js>"myMethod.deprecated = foo,bar"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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.
- *
- * <h5 class='section'>Example:</h5>
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(
- * name=<js>"POST"</js>, path=<js>"/{a}"</js>,
- * description=<js>"This is my method."</js>,
- * parameters={
- * <ja>@Parameter</ja>(in=<js>"path"</js>, name=<js>"a"</js>, description=<js>"The 'a' attribute"</js>),
- * <ja>@Parameter</ja>(in=<js>"query"</js>, name=<js>"b"</js>, description=<js>"The 'b' parameter"</js>, required=<jk>true</jk>),
- * <ja>@Parameter</ja>(in=<js>"body"</js>, description=<js>"The HTTP content"</js>),
- * <ja>@Parameter</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.
- * <p class='bcode'>
- * <jk>MyClass.myMethod.description</jk> = <js>This is my method.</js>
- * <jk>MyClass.myMethod.req.path.a.description</jk> = <js>The 'a' attribute</js>
- * <jk>MyClass.myMethod.req.query.b.description</jk> = <js>The 'b' parameter</js>
- * <jk>MyClass.myMethod.req.body.description</jk> = <js>The HTTP content</js>
- * <jk>MyClass.myMethod.req.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.
- * <p>
- * These annotations can contain variables (e.g. "$L{my.localized.variable}").
- * <p>
- * Corresponds to the swagger field <code>/paths/{path}/{method}/parameters</code>.
- */
- Parameter[] 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 Swagger page.
- *
- * <h5 class='section'>Example:</h5>
- * <p class='bcode'>
- * <ja>@RestMethod</ja>(
- * name=<js>"GET"</js>, path=<js>"/"</js>,
- * responses={
- * <ja>@Response</ja>(200),
- * <ja>@Response</ja>(
- * value=302,
- * description=<js>"Thing wasn't found here"</js>,
- * headers={
- * <ja>@Parameter</ja>(name=<js>"Location"</js>, description=<js>"The place to find the thing"</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.
- * <p class='bcode'>
- * <jk>MyClass.myMethod.res.200.description</jk> = <js>OK</js>
- * <jk>MyClass.myMethod.res.302.description</jk> = <js>Thing wasn't found here</js>
- * <jk>MyClass.myMethod.res.302.header.Location.description</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.
- * <p>
- * These annotations can contain variables (e.g. "$L{my.localized.variable}").
- */
- Response[] responses() default {};
-
- /**
* Specifies whether this method can be called based on the client version.
* <p>
* The client version is identified via the HTTP request header identified by {@link RestResource#clientVersionHeader()} which
@@ -573,17 +433,22 @@ public @interface RestMethod {
String clientVersion() default "";
/**
- * Overrides the HTML page title defined on the servlet via the {@link RestResource#pageTitle() @RestResource.pageTitle()} annotation.
+ * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly
+ * generate arbitrary replacement text.
+ * <p>
+ * Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
*/
- String pageTitle() default "";
+ Class<? extends Widget>[] widgets() default {};
/**
- * Overrides the HTML page text defined on the servlet via the {@link RestResource#pageText() @RestResource.pageText()} annotation.
+ * Provides swagger-specific metadata on this method.
*/
- String pageText() default "";
+ MethodSwagger swagger() default @MethodSwagger;
/**
- * Overrides the HTML page links defined on the servlet via the {@link RestResource#pageLinks() @RestResource.pageLinks()} annotation.
+ * Provides HTML-doc-specific metadata on this method.
+ * <p>
+ * Information provided here overrides information provided in the servlet-level annotation.
*/
- String pageLinks() default "";
+ HtmlDoc htmldoc() default @HtmlDoc;
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestResource.java b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
index 5e86742..321b11d 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/annotation/RestResource.java
@@ -21,12 +21,12 @@ import javax.servlet.http.*;
import org.apache.juneau.*;
import org.apache.juneau.encoders.Encoder;
-import org.apache.juneau.html.*;
import org.apache.juneau.ini.*;
import org.apache.juneau.jena.*;
import org.apache.juneau.json.*;
import org.apache.juneau.parser.*;
import org.apache.juneau.rest.*;
+import org.apache.juneau.rest.widget.*;
import org.apache.juneau.serializer.*;
import org.apache.juneau.transform.*;
import org.apache.juneau.utils.*;
@@ -348,7 +348,7 @@ public @interface RestResource {
/**
* Optional servlet title.
* <p>
- * It is used to populate the Swagger title field and as a default value for the {@link #pageTitle()} value.
+ * It is used to populate the Swagger title field and as a default value for the {@link HtmlDoc#title()} value.
* This value can be retrieved programmatically through the {@link RestRequest#getServletTitle()} method.
* <p>
* The default value pulls the label from the <code>label</code> entry in the servlet resource bundle.
@@ -365,7 +365,7 @@ public @interface RestResource {
/**
* Optional servlet description.
* <p>
- * It is used to populate the Swagger description field and as a default value for the {@link #pageText()} value.
+ * It is used to populate the Swagger description field and as a default value for the {@link HtmlDoc#description()} value.
* This value can be retrieved programmatically through the {@link RestRequest#getServletDescription()} method.
* <p>
* The default value pulls the description from the <code>description</code> entry in the servlet resource bundle.
@@ -380,161 +380,6 @@ public @interface RestResource {
String description() default "";
/**
- * Optional servlet terms-of-service for this API.
- * <p>
- * It is used to populate the Swagger terms-of-service field.
- * <p>
- * The default value pulls the description from the <code>termsOfService</code> entry in the servlet resource bundle.
- * (e.g. <js>"termsOfService = foo"</js> or <js>"MyServlet.termsOfService = foo"</js>).
- * <p>
- * This field can contain variables (e.g. "$L{my.localized.variable}").
- * <p>
- * Corresponds to the swagger field <code>/info/termsOfService</code>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTermsOfService(RestRequest)} method.
- */
- 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.
- * <p>
- * A simplified JSON string with the following fields:
- * <p class='bcode'>
- * {
- * name: string,
- * url: string,
- * email: string
- * }
- * </p>
- * <p>
- * The default value pulls the description from the <code>contact</code> entry in the servlet resource bundle.
- * (e.g. <js>"contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js> or <js>"MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getContact(RestRequest)} method.
- */
- 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.
- * <p>
- * A simplified JSON string with the following fields:
- * <p class='bcode'>
- * {
- * name: string,
- * url: string
- * }
- * </p>
- * <p>
- * The default value pulls the description from the <code>license</code> entry in the servlet resource bundle.
- * (e.g. <js>"license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> or <js>"MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getLicense(RestRequest)} method.
- */
- 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.
- * <p>
- * The default value pulls the description from the <code>version</code> entry in the servlet resource bundle.
- * (e.g. <js>"version = 2.0"</js> or <js>"MyServlet.version = 2.0"</js>).
- * <p>
- * This field can contain variables (e.g. "$L{my.localized.variable}").
- * <p>
- * Corresponds to the swagger field <code>/info/version</code>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getVersion(RestRequest)} method.
- */
- 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.
- * <p>
- * A simplified JSON string with the following fields:
- * <p class='bcode'>
- * [
- * {
- * name: string,
- * description: string,
- * externalDocs: {
- * description: string,
- * url: string
- * }
- * }
- * ]
- * </p>
- * <p>
- * The default value pulls the description from the <code>tags</code> entry in the servlet resource bundle.
- * (e.g. <js>"tags = [{name:'Foo',description:'Foobar'}]"</js> or <js>"MyServlet.tags = [{name:'Foo',description:'Foobar'}]"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTags(RestRequest)} method.
- */
- 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.
- * <p>
- * A simplified JSON string with the following fields:
- * <p class='bcode'>
- * {
- * description: string,
- * url: string
- * }
- * </p>
- * <p>
- * The default value pulls the description from the <code>externalDocs</code> entry in the servlet resource bundle.
- * (e.g. <js>"externalDocs = {url:'http://juneau.apache.org'}"</js> or <js>"MyServlet.externalDocs = {url:'http://juneau.apache.org'}"</js>).
- *
- * <h5 class='section'>Example:</h5>
- * <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>.
- * <p>
- * The programmatic equivalent to this annotation is the {@link RestInfoProvider#getExternalDocs(RestRequest)} method.
- */
- String externalDocs() default "";
-
- /**
* Optional location of configuration file for this servlet.
* <p>
* The configuration file .
@@ -728,116 +573,85 @@ public @interface RestResource {
Class<? extends RestInfoProvider> infoProvider() default RestInfoProvider.class;
/**
- * Specifies the page title to use on the HTML view of all pages produced by this resource.
- * <p>
- * This annotation has no effect on any serializers other than {@link HtmlDocSerializer} and is a shorthand method
- * for setting the {@link HtmlDocSerializerContext#HTMLDOC_title} property:
- * <p class='bcode'>
- * <ja>@RestResource</ja>(
- * properties={
- * <ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>, value=<js>"My Resource Page"</js>)
- * }
- * )
- * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
- * </p>
- * <p>
- * If not specified, the page title is pulled from one of the following locations:
- * <ol>
- * <li><code>{servletClass}.{methodName}.pageTitle</code> resource bundle value.
- * <li><code>{servletClass}.pageTitle</code> resource bundle value.
- * <li><code><ja>@RestResource</ja>(title)</code> annotation.
- * <li><code>{servletClass}.title</code> resource bundle value.
- * <li><code>info/title</code> entry in swagger file.
- * <ol>
+ * Specifies the serializer listener class to use for listening for non-fatal errors.
+ */
+ Class<? extends SerializerListener> serializerListener() default SerializerListener.class;
+
+ /**
+ * Specifies the parser listener class to use for listening for non-fatal errors.
+ */
+ Class<? extends ParserListener> parserListener() default ParserListener.class;
+
+ /**
+ * Defines widgets that can be used in conjunction with string variables of the form <js>"$W{name}"</js>to quickly
+ * generate arbitrary replacement text.
* <p>
- * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
+ * Widgets are inherited from parent to child, but can be overridden by reusing the widget name.
* <p>
- * The programmatic equivalent to this annotation are the {@link RestConfig#setPageTitle(String)}/{@link RestResponse#setPageTitle(Object)} methods.
- * <ul class='doctree'>
- * <li class='info'>
- * In most cases, you'll simply want to use the <code>@RestResource(title)</code> annotation to specify the page title.
- * However, this annotation is provided in cases where you want the page title to be different that the one
- * shown in the swagger document.
- * </ul>
+ * See {@link #htmldoc()} for an example of usage.
*/
- String pageTitle() default "";
+ Class<? extends Widget>[] widgets() default {};
/**
- * Specifies the page text to use on the HTML view of all pages produced by this resource.
+ * Provides swagger-specific metadata on this resource.
* <p>
- * The page text is portion of the page immediately under the title and above the links.
- * <p>
- * This annotation has no effect on any serializers other than {@link HtmlDocSerializer} and is a shorthand method
- * for setting the {@link HtmlDocSerializerContext#HTMLDOC_text} property:
+ * Used to populate the auto-generated OPTIONS swagger documentation.
+ *
+ * <h5 class='section'>Example:</h5>
* <p class='bcode'>
* <ja>@RestResource</ja>(
- * properties={
- * <ja>@Property</ja>(name=<jsf>HTMLDOC_text</jsf>, value=<js>"This is my awesome resource page"</js>)
- * }
+ * path=<js>"/addressBook"</js>,
+ *
+ * <jc>// Swagger info.</jc>
+ * swagger=<ja>@ResourceSwagger</ja>(
+ * contact=<js>"{name:'John Smith',email:'john@smith.com'}"</js>,
+ * license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>,
+ * version=<js>"2.0"</js>,
+ * termsOfService=<js>"You're on your own."</js>,
+ * tags=<js>"[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]"</js>,
+ * externalDocs=<js>"{description:'Home page',url:'http://juneau.apache.org'}"</js>
+ * )
* )
- * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
* </p>
- * If not specified, the page title is pulled from one of the following locations:
- * <ol>
- * <li><code>{servletClass}.{methodName}.pageText</code> resource bundle value.
- * <li><code>{servletClass}.pageText</code> resource bundle value.
- * <li><code><ja>@RestMethod</ja>(summary)</code> annotation.
- * <li><code>{servletClass}.{methodName}.summary</code> resource bundle value.
- * <li><code>summary</code> entry in swagger file for method.
- * <li><code>{servletClass}.description</code> resource bundle value.
- * <li><code>info/description</code> entry in swagger file.
- * <ol>
- * <p>
- * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
- * <p>
- * The programmatic equivalent to this annotation are the {@link RestConfig#setPageText(String)}/{@link RestResponse#setPageText(Object)} methods.
- * <ul class='doctree'>
- * <li class='info'>
- * In most cases, you'll simply want to use the <code>@RestResource(description)</code> or <code>@RestMethod(summary)</code> annotations to specify the page text.
- * However, this annotation is provided in cases where you want the text to be different that the values shown in the swagger document.
- * </ul>
*/
- String pageText() default "";
+ ResourceSwagger swagger() default @ResourceSwagger;
/**
- * Specifies the page hyperlinks to use on the HTML view of all pages produced by this resource.
- * <p>
- * The page links is positioned immediately under the title and text.
+ * Provides HTML-doc-specific metadata on this method.
* <p>
- * This annotation has no effect on any serializers other than {@link HtmlDocSerializer} and is a shorthand method
- * for setting the {@link HtmlDocSerializerContext#HTMLDOC_text} property:
+ * Used to customize the output from the HTML Doc serializer.
* <p class='bcode'>
* <ja>@RestResource</ja>(
- * properties={
- * <ja>@Property</ja>(name=<jsf>HTMLDOC_links</jsf>, value=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>)
+ * path=<js>"/addressBook"</js>,
+ *
+ * <jc>// Links on the HTML rendition page.
+ * // "request:/..." URIs are relative to the request URI.
+ * // "servlet:/..." URIs are relative to the servlet URI.
+ * // "$C{...}" variables are pulled from the config file.</jc>
+ * htmldoc=<ja>@HtmlDoc</ja>(
+ * links=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS',source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java'}"</js>,
+ * aside=<js>""</js>
+ * + <js>"<div style='max-width:400px;min-width:200px'>"</js>
+ * + <js>" <p>Proof-of-concept resource that shows off the capabilities of working with POJO resources.</p>"</js>
+ * + <js>" <p>Provides examples of: </p>"</js>
+ * + <js>" <ul>"</js>
+ * + <js>" <li>XML and RDF namespaces"</js>
+ * + <js>" <li>Swagger documentation"</js>
+ * + <js>" <li>Widgets"</js>
+ * + <js>" </ul>"</js>
+ * + <js>" <p style='text-weight:bold;text-decoration:underline;'>Available Content Types</p>"</js>
+ * + <js>" $W{contentTypeLinks}"</js>
+ * + <js>"</div>"</js>,
+ * footer=<js>"$W{poweredByJuneau}"</js>
+ * ),
+ *
+ * <jc>// Widgets for $W variables above.</jc>
+ * widgets={
+ * PoweredByJuneauWidget.<jk>class</jk>,
+ * ContentTypeLinksWidget.<jk>class</jk>
* }
* )
- * <jk>public class</jk> MyResource <jk>extends</jk> RestServletDefault {
* </p>
- * <p>
- * The format of this value is a lax-JSON string of key/value pairs where the keys are the link text and the values are relative (to the servlet) or
- * absolute URLs.
- * If not specified, the page title is pulled from one of the following locations:
- * <ol>
- * <li><code>{servletClass}.{methodName}.pageLinks</code> resource bundle value.
- * <li><code>{servletClass}.pageLinks</code> resource bundle value.
- * <ol>
- * <p>
- * This field can contain variables (e.g. <js>"$L{my.localized.variable}"</js>).
- * <p>
- * This field can also use URIs of any support type in {@link UriResolver}.
- * <p>
- * The programmatic equivalent to this annotation are the {@link RestConfig#setPageLinks(String)}/{@link RestResponse#setPageLinks(Object)} methods.
*/
- String pageLinks() default "";
-
- /**
- * Specifies the serializer listener class to use for listening for non-fatal errors.
- */
- Class<? extends SerializerListener> serializerListener() default SerializerListener.class;
-
- /**
- * Specifies the parser listener class to use for listening for non-fatal errors.
- */
- Class<? extends ParserListener> parserListener() default ParserListener.class;
+ HtmlDoc htmldoc() default @HtmlDoc;
}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/jena/RestServletJenaDefault.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/jena/RestServletJenaDefault.java b/juneau-rest/src/main/java/org/apache/juneau/rest/jena/RestServletJenaDefault.java
index 4b26bcb..a2099d3 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/jena/RestServletJenaDefault.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/jena/RestServletJenaDefault.java
@@ -200,7 +200,6 @@ import org.apache.juneau.xml.*;
UrlEncodingSerializer.class,
MsgPackSerializer.class,
SoapXmlSerializer.class,
- JsoSerializer.class,
PlainTextSerializer.class,
RdfSerializer.Xml.class,
RdfSerializer.XmlAbbrev.class,
@@ -239,8 +238,10 @@ public abstract class RestServletJenaDefault extends RestServlet {
*/
@RestMethod(name="OPTIONS", path="/*",
summary="Resource options",
- pageLinks="{back:'$R{servletURI}'}",
- description="Resource options"
+ description="Resource options",
+ htmldoc=@HtmlDoc(
+ links="{back:'$R{servletURI}'}"
+ )
)
public Swagger getOptions(RestRequest req) {
return req.getSwagger();
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/package.html
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/package.html b/juneau-rest/src/main/java/org/apache/juneau/rest/package.html
index 5214b64..a5bed6e 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/package.html
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/package.html
@@ -226,7 +226,9 @@
*/</jd>
<ja>@RestResource</ja>(
messages=<js>"nls/HelloWorldResource"</js>,
- pageLinks=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>
+ htmldoc=<ja>@HtmlDoc</ja>(
+ links=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>
+ )
)
<jk>public class</jk> HelloWorldResource <jk>extends</jk> Resource {
@@ -1084,7 +1086,9 @@
*/</jd>
<ja>@RestMethod</ja>(name=<js>"OPTIONS"</js>, path=<js>"/*"</js>,
summary=<js>"Resource options"</js>,
- pageLinks=<js>"{back:'$R{servletURI}'}"</js>
+ htmldoc=<ja>@HtmlDoc</ja>(
+ links=<js>"{back:'$R{servletURI}'}"</js>
+ )
)
<jk>public</jk> Swagger getOptions(RestRequest req) {
<jk>return</jk> req.getSwagger();
@@ -1194,8 +1198,8 @@
<img class='bordered' src='doc-files/Options2.png'>
<p>
This method is described through the {@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()},
- {@link org.apache.juneau.rest.annotation.RestMethod#parameters() @RestMethod.parameters()},
- and {@link org.apache.juneau.rest.annotation.RestMethod#responses() @RestMethod.responses()} annotations.
+ {@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod.swagger()},
+ and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} annotations.
</p>
<p class='bcode'>
<ja>@RestMethod</ja>(
@@ -1275,7 +1279,7 @@
<td>
A description of the HTTP request body.
</td>
- <td>{@link org.apache.juneau.rest.annotation.RestMethod#parameters() @RestMethod.parameters()}</td>
+ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}</td>
</tr>
<tr>
<td><ck>[javaMethodName].req.[category].[name].description</ck></td>
@@ -1283,38 +1287,35 @@
A request input variable.
<br>Categories: <l>path, query, formData, header</l>
</td>
- <td>{@link org.apache.juneau.rest.annotation.RestMethod#parameters() @RestMethod.parameters()}</td>
+ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}</td>
</tr>
<tr>
<td><ck>[javaMethodName].res.[code].description</ck></td>
<td>
A possible HTTP response code and description.
</td>
- <td>{@link org.apache.juneau.rest.annotation.RestMethod#responses() @RestMethod.responses()}</td>
+ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}</td>
</tr>
<tr>
<td><ck>[javaMethodName].res.[code].body.description</ck></td>
<td>
A description of response content for the specified HTTP response.
</td>
- <td>{@link org.apache.juneau.rest.annotation.RestMethod#responses() @RestMethod.responses()}</td>
+ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}</td>
</tr>
<tr>
<td><ck>[javaMethodName].res.[code].header.[name].description</ck></td>
<td>
A response header.
</td>
- <td>{@link org.apache.juneau.rest.annotation.RestMethod#responses() @RestMethod.responses()}</td>
+ <td>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}</td>
</tr>
</table>
<h6 class='topic'>Additional Information</h6>
<ul class='doctree'>
<li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#description() @RestMethod.description()}
- <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#parameters() @RestMethod.parameters()}
- <li class='ja'>{@link org.apache.juneau.rest.annotation.RestMethod#responses() @RestMethod.responses()}
- <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getServletTitle()}
- <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getServletDescription()}
- <li class='jm'>{@link org.apache.juneau.rest.RestRequest#getMethodDescription()}
+ <li class='ja'>{@link org.apache.juneau.rest.annotation.MethodSwagger#parameters() @MethodSwagger.parameters()}
+ <li class='ja'>{@link org.apache.juneau.rest.annotation.MethodSwagger#responses() @MethodSwagger.responses()}
</ul>
</div>
@@ -2174,7 +2175,9 @@
messages=<js>"nls/UrlEncodedFormResource"</js>,
title=<js>"URL-encoded Form Post Resource"</js>,
description=<js>"Shows how form posts are converted into beans."</js>,
- pageLinks=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>
+ htmldoc=<ja>@HtmlDoc</ja>(
+ links=<js>"{up:'request:/..',options:'servlet:/?method=OPTIONS'}"</js>
+ )
)
<jk>public class</jk> UrlEncodedFormResource <jk>extends</jk> Resource {
<jk>private static final long</jk> <jsf>serialVersionUID</jsf> = 1L;
@@ -2929,7 +2932,9 @@
messages=<js>"nls/PhotosResource"</js>,
title=<js>"Photo REST service"</js>,
description=<js>"Use a tool like Poster to upload and retrieve jpeg and png images."</js>,
- pageLinks=<js>"{options:'?method=OPTIONS'}"</js>
+ htmldoc=<ja>@HtmlDoc</ja>(
+ links=<js>"{options:'?method=OPTIONS'}"</js>
+ )
)
<jk>public class</jk> PhotosResource <jk>extends</jk> RestServletDefault {
@@ -3215,7 +3220,9 @@
// "request:/..." URIs are relative to the request URI.
// "servlet:/..." URIs are relative to the servlet URI.
// "$C{...}" variables are pulled from the config file.</jc>
- pageLinks=<js>"{up:'request:/..', options:'servlet:/?method=OPTIONS', source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java'}"</js>,
+ htmldoc=<ja>@HtmlDoc</ja>(
+ links=<js>"{up:'request:/..', options:'servlet:/?method=OPTIONS', source:'$C{Source/gitHub}/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java'}"</js>
+ ),
<jc>// Properties that get applied to all serializers and parsers.</jc>
properties={
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/f4812b7c/juneau-rest/src/main/java/org/apache/juneau/rest/response/DefaultHandler.java
----------------------------------------------------------------------
diff --git a/juneau-rest/src/main/java/org/apache/juneau/rest/response/DefaultHandler.java b/juneau-rest/src/main/java/org/apache/juneau/rest/response/DefaultHandler.java
index 158aca7..fe7aab6 100644
--- a/juneau-rest/src/main/java/org/apache/juneau/rest/response/DefaultHandler.java
+++ b/juneau-rest/src/main/java/org/apache/juneau/rest/response/DefaultHandler.java
@@ -19,6 +19,7 @@ import java.io.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.http.*;
+import org.apache.juneau.internal.*;
import org.apache.juneau.rest.*;
import org.apache.juneau.serializer.*;
@@ -58,11 +59,21 @@ public class DefaultHandler implements ResponseHandler {
}
p.append("mediaType", mediaType).append("characterEncoding", res.getCharacterEncoding());
if (! s.isWriterSerializer()) {
- OutputStreamSerializer s2 = (OutputStreamSerializer)s;
- OutputStream os = res.getNegotiatedOutputStream();
- SerializerSession session = s.createSession(os, p, req.getJavaMethod(), req.getLocale(), req.getHeaders().getTimeZone(), mediaType, req.getUriContext());
- s2.serialize(session, output);
- os.close();
+ if (req.isPlainText()) {
+ OutputStreamSerializer s2 = (OutputStreamSerializer)s;
+ Writer w = res.getNegotiatedWriter();
+ ByteArrayOutputStream baos = new ByteArrayOutputStream();
+ SerializerSession session = s.createSession(baos, p, req.getJavaMethod(), req.getLocale(), req.getHeaders().getTimeZone(), mediaType, req.getUriContext());
+ s2.serialize(session, output);
+ w.write(StringUtils.toHex(baos.toByteArray()));
+ w.close();
+ } else {
+ OutputStreamSerializer s2 = (OutputStreamSerializer)s;
+ OutputStream os = res.getNegotiatedOutputStream();
+ SerializerSession session = s.createSession(os, p, req.getJavaMethod(), req.getLocale(), req.getHeaders().getTimeZone(), mediaType, req.getUriContext());
+ s2.serialize(session, output);
+ os.close();
+ }
} else {
WriterSerializer s2 = (WriterSerializer)s;
Writer w = res.getNegotiatedWriter();