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:'[email protected]'}"</js> or <js>"MyServlet.contact = {name:'John Smith',email:'[email protected]'}"</js>). + * + * <h5 class='section'>Example:</h5> + * <p class='bcode'> + * <ja>@RestResource</ja>(contact=<js>"{name:'John Smith',email:'[email protected]'}"</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:'[email protected]'}"</js> or <js>"MyServlet.contact = {name:'John Smith',email:'[email protected]'}"</js>). - * - * <h5 class='section'>Example:</h5> - * <p class='bcode'> - * <ja>@RestResource</ja>(contact=<js>"{name:'John Smith',email:'[email protected]'}"</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:'[email protected]'}"</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();
