This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new 861fea2 Javadocs
861fea2 is described below
commit 861fea225a9cb8e64bf5315f3d2906df33970c79
Author: JamesBognar <jamesbog...@apache.org>
AuthorDate: Mon Sep 10 19:30:58 2018 -0400
Javadocs
---
juneau-doc/docs.txt | 13 +-
juneau-doc/src/main/javadoc/overview.html | 436 +++++++++++----------
.../03.Instantiation/02.BasicRestServlet.html | 4 +-
...tInfoProvider.html => 26.RestInfoProvider.html} | 2 +-
.../01.BasicRestInfoProvider.html} | 21 +-
.../Topics/07.juneau-rest-server/26.Swagger.html | 363 -----------------
.../26.Swagger/02.BasicRestInfoProvider.html | 91 -----
.../{37.HTTP2.html => 27.Swagger.html} | 18 +-
.../27.Swagger/01.BasicRestServlet.html | 96 +++++
.../27.Swagger/02.BasicSwaggerInfo.html | 177 +++++++++
.../07.juneau-rest-server/27.Swagger/03.Tags.html | 113 ++++++
.../04.Operations.html} | 7 +-
.../05.Parameters.html} | 7 +-
.../06.ParameterExamples.html} | 7 +-
.../07.Responses.html} | 7 +-
.../08.ResponseExamples.html} | 7 +-
.../{37.HTTP2.html => 27.Swagger/09.Models.html} | 7 +-
...ocAnnotation.html => 28.HtmlDocAnnotation.html} | 0
.../01.Widgets.html | 0
.../02.PredefinedWidgets.html | 0
.../03.UiCustomization.html | 0
.../04.Stylesheets.html | 0
...erver.HtmlDocAnnotation.PredefinedWidgets.1.png | Bin
...erver.HtmlDocAnnotation.PredefinedWidgets.2.png | Bin
...erver.HtmlDocAnnotation.PredefinedWidgets.3.png | Bin
...erver.HtmlDocAnnotation.PredefinedWidgets.4.png | Bin
....DefaultHeaders.html => 29.DefaultHeaders.html} | 0
...ndling.html => 30.LoggingAndErrorHandling.html} | 0
...ttpStatusCodes.html => 31.HttpStatusCodes.html} | 0
...Methods.html => 32.OverloadingHttpMethods.html} | 0
...InParameters.html => 33.BuiltInParameters.html} | 0
...rs.html => 34.CustomSerializersAndParsers.html} | 0
...34.UsingWithOsgi.html => 35.UsingWithOsgi.html} | 0
.../{35.UnitTesting.html => 36.UnitTesting.html} | 0
.../{36.Injection.html => 37.Injection.html} | 0
.../{37.HTTP2.html => 38.HTTP2.html} | 0
.../{38.OtherNotes.html => 39.OtherNotes.html} | 0
.../org/apache/juneau/rest/RestInfoProvider.java | 46 +++
.../org/apache/juneau/rest/vars/RequestVar.java | 1 -
39 files changed, 721 insertions(+), 702 deletions(-)
diff --git a/juneau-doc/docs.txt b/juneau-doc/docs.txt
index f353faa..2bf2f43 100644
--- a/juneau-doc/docs.txt
+++ b/juneau-doc/docs.txt
@@ -289,6 +289,8 @@ juneau-rest-server.OverloadingHttpMethods =
#juneau-rest-server.OverloadingHttpM
juneau-rest-server.Parsers = #juneau-rest-server.Parsers, Overview >
juneau-rest-server > Parsers
juneau-rest-server.Properties = #juneau-rest-server.Properties, Overview >
juneau-rest-server > Properties
juneau-rest-server.RestContext = #juneau-rest-server.RestContext, Overview >
juneau-rest-server > RestContext
+juneau-rest-server.RestInfoProvider = #juneau-rest-server.RestInfoProvider,
Overview > juneau-rest-server > RestInfoProvider
+juneau-rest-server.RestInfoProvider.BasicRestInfoProvider =
#juneau-rest-server.RestInfoProvider.BasicRestInfoProvider, Overview >
juneau-rest-server > RestInfoProvider > BasicRestInfoProvider
juneau-rest-server.RestMethod = #juneau-rest-server.RestMethod, Overview >
juneau-rest-server > @RestMethod
juneau-rest-server.RestMethod.MethodParameters =
#juneau-rest-server.RestMethod.MethodParameters, Overview > juneau-rest-server
> @RestMethod > Java Method Parameters
juneau-rest-server.RestMethod.MethodReturnTypes =
#juneau-rest-server.RestMethod.MethodReturnTypes, Overview > juneau-rest-server
> @RestMethod > Method Return Types
@@ -312,8 +314,15 @@ juneau-rest-server.Serializers =
#juneau-rest-server.Serializers, Overview > jun
juneau-rest-server.StaticFiles = #juneau-rest-server.StaticFiles, Overview >
juneau-rest-server > Static files
juneau-rest-server.SvlVariables = #juneau-rest-server.SvlVariables, Overview >
juneau-rest-server > SVL Variables
juneau-rest-server.Swagger = #juneau-rest-server.Swagger, Overview >
juneau-rest-server > Swagger
-juneau-rest-server.Swagger.BasicRestInfoProvider =
#juneau-rest-server.Swagger.BasicRestInfoProvider, Overview >
juneau-rest-server > Swagger > BasicRestInfoProvider
-juneau-rest-server.Swagger.RestInfoProvider =
#juneau-rest-server.Swagger.RestInfoProvider, Overview > juneau-rest-server >
Swagger > RestInfoProvider
+juneau-rest-server.Swagger.BasicRestServlet =
#juneau-rest-server.Swagger.BasicRestServlet, Overview > juneau-rest-server >
Swagger > BasicRestServlet
+juneau-rest-server.Swagger.BasicSwaggerInfo =
#juneau-rest-server.Swagger.BasicSwaggerInfo, Overview > juneau-rest-server >
Swagger > Basic Swagger Info
+juneau-rest-server.Swagger.Models = #juneau-rest-server.Swagger.Models,
Overview > juneau-rest-server > Swagger > Response Examples
+juneau-rest-server.Swagger.Operations =
#juneau-rest-server.Swagger.Operations, Overview > juneau-rest-server > Swagger
> Operations
+juneau-rest-server.Swagger.ParameterExamples =
#juneau-rest-server.Swagger.ParameterExamples, Overview > juneau-rest-server >
Swagger > Parameter Examples
+juneau-rest-server.Swagger.Parameters =
#juneau-rest-server.Swagger.Parameters, Overview > juneau-rest-server > Swagger
> Parameters
+juneau-rest-server.Swagger.ResponseExamples =
#juneau-rest-server.Swagger.ResponseExamples, Overview > juneau-rest-server >
Swagger > Response Examples
+juneau-rest-server.Swagger.Responses = #juneau-rest-server.Swagger.Responses,
Overview > juneau-rest-server > Swagger > Responses
+juneau-rest-server.Swagger.Tags = #juneau-rest-server.Swagger.Tags, Overview >
juneau-rest-server > Swagger > Tags
juneau-rest-server.Transforms = #juneau-rest-server.Transforms, Overview >
juneau-rest-server > Transforms
juneau-rest-server.URIs = #juneau-rest-server.URIs, Overview >
juneau-rest-server > URIs
juneau-rest-server.UnitTesting = #juneau-rest-server.UnitTesting, Overview >
juneau-rest-server > Serverless Unit Testing
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 497d2b5..62dcb1a 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -329,10 +329,21 @@
<li><p class=''><a class='doclink'
href='#juneau-rest-server.ConfigurationFiles'>Configuration Files</a></p>
<li><p class=''><a class='doclink'
href='#juneau-rest-server.StaticFiles'>Static files</a></p>
<li><p class=''><a class='doclink'
href='#juneau-rest-server.ClientVersioning'>Client Versioning</a></p>
- <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger'>Swagger</a></p>
+ <li><p class='updated'><a class='doclink'
href='#juneau-rest-server.RestInfoProvider'>RestInfoProvider</a></p>
<ol>
- <li><p class=''><a class='doclink'
href='#juneau-rest-server.Swagger.RestInfoProvider'>RestInfoProvider</a></p>
- <li><p class=''><a class='doclink'
href='#juneau-rest-server.Swagger.BasicRestInfoProvider'>BasicRestInfoProvider</a></p>
+ <li><p class='updated'><a class='doclink'
href='#juneau-rest-server.RestInfoProvider.BasicRestInfoProvider'>BasicRestInfoProvider</a></p>
+ </ol>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.Swagger'>Swagger</a></p>
+ <ol>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.Swagger.BasicRestServlet'>BasicRestServlet</a></p>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.Swagger.BasicSwaggerInfo'>Basic Swagger Info</a></p>
+ <li><p class='new'><a class='doclink'
href='#juneau-rest-server.Swagger.Tags'>Tags</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.Operations'>Operations</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.Parameters'>Parameters</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.ParameterExamples'>Parameter Examples</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.Responses'>Responses</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.ResponseExamples'>Response Examples</a></p>
+ <li><p class='todo'><a class='doclink'
href='#juneau-rest-server.Swagger.Models'>Response Examples</a></p>
</ol>
<li><p class=''><a class='doclink'
href='#juneau-rest-server.HtmlDocAnnotation'>@HtmlDoc</a></p>
<ol>
@@ -12992,43 +13003,21 @@
<js>"up: request:/.."</js>,
<js>"options: servlet:/?method=OPTIONS"</js>
}
- ),
-
- <jc>// POJO swaps to apply to all serializers/parsers.</jc>
- pojoSwaps={
- <jc>// Use the SwaggerUI swap when rendering Swagger
beans.</jc>
- SwaggerUI.<jk>class</jk>
- },
-
- <jc>// Properties to apply to all serializers/parsers and
REST-specific API objects.</jc>
- properties={
- <jc>// Add descriptions to the following types when not
specified:</jc>
-
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addDescriptionsTo</jsf>,
value=<js>"bean,collection,array,map,enum"</js>),
-
- <jc>// Automatically add examples to the following
types:</jc>
-
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addExamplesTo</jsf>,
value=<js>"bean,collection,array,map"</js>),
-
- <jc>// Don't generate schema information on the Swagger
bean itself or HTML beans.</jc>
-
<ja>@Property</ja>(name=<jsf>INFOPROVIDER_ignoreTypes</jsf>,
value="<js>Swagger,org.apache.juneau.dto.html5.*"</js>)
- },
-
- <jc>// Shortcut for boolean properties.</jc>
- flags={
- <jc>// Use $ref references for bean definitions to
reduce duplication in Swagger.</jc>
- <jsf>JSONSCHEMA_useBeanDefs</jsf>
- }
+ )
)
<jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {
<jd>/**
* [OPTIONS /*] - Show resource options.
*
- * @param req The HTTP request.
- * @return A bean containing the contents for the OPTIONS page.
+ * <ja>@param</ja> req The HTTP request.
+ * <ja>@return</ja> A bean containing the contents for the
OPTIONS page.
*/</jd>
<ja>@RestMethod</ja>(name=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
+
summary=<js>"Swagger documentation"</js>,
description=<js>"Swagger documentation for this
resource."</js>,
+
htmldoc=<ja>@HtmlDoc</ja>(
<jc>// Override the nav links for the swagger
page.</jc>
navlinks={
@@ -13037,7 +13026,31 @@
},
<jc>// Never show aside contents of page
inherited from class.</jc>
aside=<js>"NONE"</js>
- )
+ ),
+
+ <jc>// POJO swaps to apply to all
serializers/parsers.</jc>
+ pojoSwaps={
+ <jc>// Use the SwaggerUI swap when rendering
Swagger beans.</jc>
+ SwaggerUI.<jk>class</jk>
+ },
+
+ <jc>// Properties to apply to all serializers/parsers
and REST-specific API objects.</jc>
+ properties={
+ <jc>// Add descriptions to the following types
when not specified:</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addDescriptionsTo</jsf>,
value=<js>"bean,collection,array,map,enum"</js>),
+
+ <jc>// Automatically add examples to the
following types:</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addExamplesTo</jsf>,
value=<js>"bean,collection,array,map"</js>),
+
+ <jc>// Don't generate schema information on the
Swagger bean itself or HTML beans.</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_ignoreTypes</jsf>,
value="<js>Swagger,org.apache.juneau.dto.html5.*"</js>)
+ },
+
+ <jc>// Shortcut for boolean properties.</jc>
+ flags={
+ <jc>// Use $ref references for bean definitions
to reduce duplication in Swagger.</jc>
+ <jsf>JSONSCHEMA_useBeanDefs</jsf>
+ }
)
<jk>public</jk> Swagger getOptions(RestRequest req) {
<jc>// Localized Swagger for this resource is available
through the RestRequest object.</jc>
@@ -18336,8 +18349,80 @@
<!--
====================================================================================================
-->
-<h3 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger' id='juneau-rest-server.Swagger'>7.26 -
Swagger</a></h3>
-<div class='topic'><!-- START: 7.26 - juneau-rest-server.Swagger -->
+<h3 class='topic updated' onclick='toggle(this)'><a
href='#juneau-rest-server.RestInfoProvider'
id='juneau-rest-server.RestInfoProvider'>7.26 - RestInfoProvider</a></h3>
+<div class='topic'><!-- START: 7.26 - juneau-rest-server.RestInfoProvider -->
+<p>
+ The {@link org.apache.juneau.rest.RestInfoProvider} class is used to
find the title
+ and description for your resource and also generate the Swagger
documentation.
+ <br>It can be overridden to provide your own custom Swagger
documentation.
+</p>
+<p>
+ The methods on this interface are:
+</p>
+<ul class='doctree'>
+ <li class='jic'>{@link org.apache.juneau.rest.RestInfoProvider}
+ <ul>
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getSwagger(RestRequest)
getSwagger(RestRequest)}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getSiteName(RestRequest)
getSiteName(RestRequest)}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)
getTitle(RestRequest)}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)
getDescription(RestRequest)}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getMethodSummary(Method,RestRequest)
getMethodSummary(Method,RestRequest)}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getMethodDescription(Method,RestRequest)
getMethodDescription(Method,RestRequest)}
+ </ul>
+</ul>
+<p>
+ The info provider in turn supplies the information returned by the
following methods:
+</p>
+<ul class='doctree'>
+ <li class='jc'>{@link org.apache.juneau.rest.RestRequest}
+ <ul>
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getSwagger() getSwagger()}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getSiteName() getSiteName()}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getResourceTitle() getResourceTitle()}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getResourceDescription()
getResourceDescription()}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getMethodSummary() getMethodSummary()}
+ <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getMethodDescription()
getMethodDescription()}
+ </ul>
+</ul>
+<p>
+ Info providers are registered through the following property:
+</p>
+<ul>
+ <li class='jf'>{@link
org.apache.juneau.rest.RestContext#REST_infoProvider}
+</ul>
+<p>
+ While you can implement this interface from scratch, you may want to
instead consider extending
+ from the <l>BasicRestInfoProvider</l> class described next.
+</p>
+
+<!--
====================================================================================================
-->
+
+<h4 class='topic updated' onclick='toggle(this)'><a
href='#juneau-rest-server.RestInfoProvider.BasicRestInfoProvider'
id='juneau-rest-server.RestInfoProvider.BasicRestInfoProvider'>7.26.1 -
BasicRestInfoProvider</a></h4>
+<div class='topic'><!-- START: 7.26.1 -
juneau-rest-server.RestInfoProvider.BasicRestInfoProvider -->
+<p>
+ The {@link org.apache.juneau.rest.BasicRestInfoProvider} class is the
default implementation of the
+ {@link org.apache.juneau.rest.RestInfoProvider} interface.
+</p>
+<p>
+ It finds and collects information gathered from the following locations:
+</p>
+<ul>
+ <li>Localized JSON Swagger files in the classpath.
+ <li>Reflection.
+ <li>Annotations.
+ <li>Properties files.
+</ul>
+<p>
+ The class itself is designed to be extended if you wish to rely mostly
on the default behavior, but tweak
+ certain aspects.
+</p>
+</div><!-- END: 7.26.1 -
juneau-rest-server.RestInfoProvider.BasicRestInfoProvider -->
+</div><!-- END: 7.26 - juneau-rest-server.RestInfoProvider -->
+
+<!--
====================================================================================================
-->
+
+<h3 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger' id='juneau-rest-server.Swagger'>7.27 -
Swagger</a></h3>
+<div class='topic'><!-- START: 7.27 - juneau-rest-server.Swagger -->
<p>
One of the most useful features of Juneau is the ability to generate
Swagger-based OPTIONS pages for self-documenting designs
(i.e. REST interfaces that document themselves).
@@ -18350,9 +18435,14 @@
Using {@link org.apache.juneau.dto.swagger.ui.SwaggerUI}, we're able to
render that JSON as a Swagger user interface:
</p>
<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.2.png'>
+
+<!--
====================================================================================================
-->
+
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.BasicRestServlet'
id='juneau-rest-server.Swagger.BasicRestServlet'>7.27.1 -
BasicRestServlet</a></h4>
+<div class='topic'><!-- START: 7.27.1 -
juneau-rest-server.Swagger.BasicRestServlet -->
<p>
Any subclass of {@link org.apache.juneau.rest.BasicRestServlet} gets an
auto-generated Swagger UI when performing an <code>OPTIONS</code>
- request with <code>Accept: text/html</code>.
+ request with <code>Accept:text/html</code>.
</p>
<p>
The underlying mechanics are simple.
@@ -18379,9 +18469,11 @@
* <ja>@param</ja> req The HTTP request.
* <ja>@return</ja> A bean containing the contents for the
OPTIONS page.
*/</jd>
- <ja>@RestMethod</ja>(name=OPTIONS, path=<js>"/*"</js>,
+ <ja>@RestMethod</ja>(name=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
+
summary=<js>"Swagger documentation"</js>,
description=<js>"Swagger documentation for this
resource."</js>,
+
htmldoc=<ja>@HtmlDoc</ja>(
<jc>// Override the nav links for the swagger
page.</jc>
navlinks={
@@ -18390,7 +18482,7 @@
},
<jc>// Never show aside contents of page
inherited from class.</jc>
aside=<js>"NONE"</js>
- )
+ ),
<jc>// POJO swaps to apply to all
serializers/parsers.</jc>
pojoSwaps={
@@ -18408,7 +18500,7 @@
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addExamplesTo</jsf>,
value=<js>"bean,collection,array,map"</js>),
<jc>// Don't generate schema information on the
Swagger bean itself or HTML beans.</jc>
-
<ja>@Property</ja>(name=<jsf>INFOPROVIDER_ignoreTypes</jsf>,
value=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>)
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_ignoreTypes</jsf>,
value=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>)
},
<jc>// Shortcut for boolean properties.</jc>
@@ -18424,10 +18516,18 @@
}
</p>
<p>
- Let's look at the various parts of the <code>Petstore</code>
application Swagger UI to see how they are defined.
+ Note that to have your resource create Swagger UI, you must either
extend from {@link org.apache.juneau.rest.BasicRestServlet} or provide
+ your own <ja>@RestMethod</ja>-annotated method that returns a {@link
org.apache.juneau.dto.swagger.Swagger} object and a {@link
org.apache.juneau.dto.swagger.ui.SwaggerUI} swap.
</p>
+</div><!-- END: 7.27.1 - juneau-rest-server.Swagger.BasicRestServlet -->
-<h5 class='topic'>General Information</h5>
+<!--
====================================================================================================
-->
+
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.BasicSwaggerInfo'
id='juneau-rest-server.Swagger.BasicSwaggerInfo'>7.27.2 - Basic Swagger
Info</a></h4>
+<div class='topic'><!-- START: 7.27.2 -
juneau-rest-server.Swagger.BasicSwaggerInfo -->
+<p>
+ Let's look at the various parts of the <code>Petstore</code>
application Swagger UI to see how they are defined.
+</p>
<p>
The top part of the page shows general information about the REST
interface:
</p>
@@ -18490,9 +18590,11 @@
title=<js>"Petstore application"</js>,
...
swagger=<ja>@ResourceSwagger</ja>(
+ <jc>// Raw Simplified JSON.</jc>
+ <jc>// Values are concatenated.
<js>"{"</js>,
<js>"swagger: '2.0',"</js>,
- <js>"version: '1.0.0',",</js>,
+ <js>"version: '1.0.0',"</js>,
...
<js>"}"</js>
),
@@ -18501,7 +18603,7 @@
<jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
</p>
<p>
- However, a more typical scenario is to define all of your Swagger as
annotations:
+ However, a more typical (and less error-prone) scenario is to define
all of your Swagger as annotations:
</p>
<p class='bpcode w800'>
<ja>@RestResource</ja>(
@@ -18583,8 +18685,12 @@
<li>Resource bundle
<li>Swagger JSON file
</ol>
+</div><!-- END: 7.27.2 - juneau-rest-server.Swagger.BasicSwaggerInfo -->
-<h5 class='topic'>Tags</h5>
+<!--
====================================================================================================
-->
+
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.Tags'
id='juneau-rest-server.Swagger.Tags'>7.27.3 - Tags</a></h4>
+<div class='topic'><!-- START: 7.27.3 - juneau-rest-server.Swagger.Tags -->
<p>
Tags allow you to group operations into general categories.
In the user interface, these can be expanded/collapsed by clicking on
the tag sections.
@@ -18681,141 +18787,67 @@
show up at the top of the page:
</p>
<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.5.png'>
+</div><!-- END: 7.27.3 - juneau-rest-server.Swagger.Tags -->
<!--
====================================================================================================
-->
-<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.RestInfoProvider'
id='juneau-rest-server.Swagger.RestInfoProvider'>7.26.1 -
RestInfoProvider</a></h4>
-<div class='topic'><!-- START: 7.26.1 -
juneau-rest-server.Swagger.RestInfoProvider -->
-<p>
- The {@link org.apache.juneau.rest.RestInfoProvider} class is used to
find the title
- and description for your resource and also generate the Swagger
documentation.
- <br>It can be overridden to provide your own custom Swagger
documentation.
-</p>
-<p>
- The methods on this interface are:
-</p>
-<ul class='doctree'>
- <li class='jic'>{@link org.apache.juneau.rest.RestInfoProvider}
- <ul>
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getSwagger(RestRequest)
getSwagger(RestRequest)}
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getSiteName(RestRequest)
getSiteName(RestRequest)}
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getTitle(RestRequest)
getTitle(RestRequest)}
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getDescription(RestRequest)
getDescription(RestRequest)}
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getMethodSummary(Method,RestRequest)
getMethodSummary(Method,RestRequest)}
- <li class='jm'>{@link
org.apache.juneau.rest.RestInfoProvider#getMethodDescription(Method,RestRequest)
getMethodDescription(Method,RestRequest)}
- </ul>
-</ul>
-<p>
- The info provider in turn supplies the information returned by the
following methods:
-</p>
-<ul class='doctree'>
- <li class='jc'>{@link org.apache.juneau.rest.RestRequest}
- <ul>
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getSwagger() getSwagger()}
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getSiteName() getSiteName()}
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getResourceTitle() getResourceTitle()}
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getResourceDescription()
getResourceDescription()}
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getMethodSummary() getMethodSummary()}
- <li class='jm'>{@link
org.apache.juneau.rest.RestRequest#getMethodDescription()
getMethodDescription()}
- </ul>
-</ul>
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.Operations'
id='juneau-rest-server.Swagger.Operations'>7.27.4 - Operations</a></h4>
+<div class='topic'><!-- START: 7.27.4 - juneau-rest-server.Swagger.Operations
-->
<p>
- Info providers are registered through the following property:
-</p>
-<ul>
- <li class='jf'>{@link
org.apache.juneau.rest.RestContext#REST_infoProvider}
-</ul>
-<p>
- While you can implement this interface from scratch, you may want to
instead consider extending
- from the <l>BasicRestInfoProvider</l> class described next.
+ TODO
</p>
-</div><!-- END: 7.26.1 - juneau-rest-server.Swagger.RestInfoProvider -->
+</div><!-- END: 7.27.4 - juneau-rest-server.Swagger.Operations -->
<!--
====================================================================================================
-->
-<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.BasicRestInfoProvider'
id='juneau-rest-server.Swagger.BasicRestInfoProvider'>7.26.2 -
BasicRestInfoProvider</a></h4>
-<div class='topic'><!-- START: 7.26.2 -
juneau-rest-server.Swagger.BasicRestInfoProvider -->
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.Parameters'
id='juneau-rest-server.Swagger.Parameters'>7.27.5 - Parameters</a></h4>
+<div class='topic'><!-- START: 7.27.5 - juneau-rest-server.Swagger.Parameters
-->
<p>
- The {@link org.apache.juneau.rest.BasicRestInfoProvider} class is the
default implementation of the
- {@link org.apache.juneau.rest.RestInfoProvider} interface.
+ TODO
</p>
+</div><!-- END: 7.27.5 - juneau-rest-server.Swagger.Parameters -->
+
+<!--
====================================================================================================
-->
+
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.ParameterExamples'
id='juneau-rest-server.Swagger.ParameterExamples'>7.27.6 - Parameter
Examples</a></h4>
+<div class='topic'><!-- START: 7.27.6 -
juneau-rest-server.Swagger.ParameterExamples -->
<p>
- It finds and collects information gathered from the following locations:
+ TODO
</p>
-<ul>
- <li>Localized JSON Swagger files in the classpath.
- <li>Reflection.
- <li> annotations.
- <li>Info provided in properties files.
-</ul>
+</div><!-- END: 7.27.6 - juneau-rest-server.Swagger.ParameterExamples -->
+
+<!--
====================================================================================================
-->
+
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.Responses'
id='juneau-rest-server.Swagger.Responses'>7.27.7 - Responses</a></h4>
+<div class='topic'><!-- START: 7.27.7 - juneau-rest-server.Swagger.Responses
-->
<p>
- The class itself is designed to be extended if you wish to rely mostly
on the default behavior, but tweak
- certain aspects.
+ TODO
</p>
+</div><!-- END: 7.27.7 - juneau-rest-server.Swagger.Responses -->
+
+<!--
====================================================================================================
-->
+
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.ResponseExamples'
id='juneau-rest-server.Swagger.ResponseExamples'>7.27.8 - Response
Examples</a></h4>
+<div class='topic'><!-- START: 7.27.8 -
juneau-rest-server.Swagger.ResponseExamples -->
<p>
- The default provider provides several options for defining Swagger
documentation on your resource:
+ TODO
</p>
-<ul class='spaced-list'>
- <li>
- Provide nothing.
- <br>You'll still get an auto-generated Swagger doc with
information gather solely through reflection, including methods, parameters,
consumes/produces, etc...
- <li>
- Specify localized JSON Swagger files on your classpath.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- MyResource_ja_JP.json
- </p>
- <li>
- Use {@link
org.apache.juneau.rest.annotation.RestResource#swagger()
@RestResource(swagger)} and {@link
org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod(swagger)}
- annotations on your resource classes and methods.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <ja>@RestMethod</ja>(
- swagger=<js>"{tags:'foo,bar,baz'}</js>
- )
- <jk>public</jk> Object myMethod() {...}
- </p>
- <li>
- Use properties files identified by the {@link
org.apache.juneau.rest.annotation.RestResource#messages
@RestResource(messages)} annotation.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <ck>MyResource.myMethod.tags</ck> = <cv>foo,bar,baz</cv>
- </p>
- <li>
- Use any combination of the above.
- <li>
- Extend the <l>BasicRestInfoProvider</l> and provide customized
behavior.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jc>// Our customized info provider.</jc>
- <jc>// Extend from the default implementation and selectively override
values.</jc>
- <jk>public class</jk> MyRestInfoProvider <jk>extends</jk>
BasicRestInfoProvider {
-
- <jc>// Must provide this constructor!</jc>
- <jk>public</jk> MyRestInfoProvider(RestContext context) {
- <jk>super</jk>(context);
- }
+</div><!-- END: 7.27.8 - juneau-rest-server.Swagger.ResponseExamples -->
- <ja>@Override</ja> <jc>/* RestInfoProvider */</jc>
- <jk>public</jk> Swagger getSwagger(RestRequest req)
<jk>throws</jk> RestException {
- Swagger s = <jk>super</jk>.getSwagger(req);
- <jc>// Made inline modifications to generated
swagger.</jc>
- <jk>return</jk> s;
- }
- }
+<!--
====================================================================================================
-->
- <jc>// Registered via annotation</jc>
- <ja>@RestResource</ja>(infoProvider=MyRestInfoProvider.<jk>class</jk>)
- <jk>public class</jk> MyResource {...}
- </p>
-</ul>
-</div><!-- END: 7.26.2 - juneau-rest-server.Swagger.BasicRestInfoProvider -->
-</div><!-- END: 7.26 - juneau-rest-server.Swagger -->
+<h4 class='topic todo' onclick='toggle(this)'><a
href='#juneau-rest-server.Swagger.Models'
id='juneau-rest-server.Swagger.Models'>7.27.9 - Response Examples</a></h4>
+<div class='topic'><!-- START: 7.27.9 - juneau-rest-server.Swagger.Models -->
+<p>
+ TODO
+</p>
+</div><!-- END: 7.27.9 - juneau-rest-server.Swagger.Models -->
+</div><!-- END: 7.27 - juneau-rest-server.Swagger -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation'
id='juneau-rest-server.HtmlDocAnnotation'>7.27 - @HtmlDoc</a></h3>
-<div class='topic'><!-- START: 7.27 - juneau-rest-server.HtmlDocAnnotation -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation'
id='juneau-rest-server.HtmlDocAnnotation'>7.28 - @HtmlDoc</a></h3>
+<div class='topic'><!-- START: 7.28 - juneau-rest-server.HtmlDocAnnotation -->
<p>
The {@link org.apache.juneau.rest.annotation.HtmlDoc @HtmlDoc}
annotation is used to customize the HTML
view of your serialized POJOs.
@@ -18937,8 +18969,8 @@
<!--
====================================================================================================
-->
-<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.Widgets'
id='juneau-rest-server.HtmlDocAnnotation.Widgets'>7.27.1 - Widgets</a></h4>
-<div class='topic'><!-- START: 7.27.1 -
juneau-rest-server.HtmlDocAnnotation.Widgets -->
+<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.Widgets'
id='juneau-rest-server.HtmlDocAnnotation.Widgets'>7.28.1 - Widgets</a></h4>
+<div class='topic'><!-- START: 7.28.1 -
juneau-rest-server.HtmlDocAnnotation.Widgets -->
<p>
The {@link org.apache.juneau.rest.widget.Widget} class allows you to
add arbitrary HTML, CSS, and Javascript
to HTML pages.
@@ -19053,12 +19085,12 @@
<ul>
<li class='jf'>{@link org.apache.juneau.rest.RestContext#REST_widgets}
</ul>
-</div><!-- END: 7.27.1 - juneau-rest-server.HtmlDocAnnotation.Widgets -->
+</div><!-- END: 7.28.1 - juneau-rest-server.HtmlDocAnnotation.Widgets -->
<!--
====================================================================================================
-->
-<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets'
id='juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets'>7.27.2 - Predefined
Widgets</a></h4>
-<div class='topic'><!-- START: 7.27.2 -
juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets -->
+<h4 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets'
id='juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets'>7.28.2 - Predefined
Widgets</a></h4>
+<div class='topic'><!-- START: 7.28.2 -
juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets -->
<p>
The {@link org.apache.juneau.rest.widget} package contains predefined
reusable widgets.
</p>
@@ -19296,12 +19328,12 @@
}
}
</p>
-</div><!-- END: 7.27.2 -
juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets -->
+</div><!-- END: 7.28.2 -
juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets -->
<!--
====================================================================================================
-->
-<h4 class='topic updated' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.UiCustomization'
id='juneau-rest-server.HtmlDocAnnotation.UiCustomization'>7.27.3 - UI
Customization</a></h4>
-<div class='topic'><!-- START: 7.27.3 -
juneau-rest-server.HtmlDocAnnotation.UiCustomization -->
+<h4 class='topic updated' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.UiCustomization'
id='juneau-rest-server.HtmlDocAnnotation.UiCustomization'>7.28.3 - UI
Customization</a></h4>
+<div class='topic'><!-- START: 7.28.3 -
juneau-rest-server.HtmlDocAnnotation.UiCustomization -->
<p>
The HTML views of POJOs can somewhat be considered a rudimentary User
Interface.
In reality, a better term for them would be a Developer Interface as
they're meant to be used
@@ -19446,12 +19478,12 @@
<ul>
<li class='link'>{@doc juneau-microservice-server.UiCustomization}
</ul>
-</div><!-- END: 7.27.3 - juneau-rest-server.HtmlDocAnnotation.UiCustomization
-->
+</div><!-- END: 7.28.3 - juneau-rest-server.HtmlDocAnnotation.UiCustomization
-->
<!--
====================================================================================================
-->
-<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.Stylesheets'
id='juneau-rest-server.HtmlDocAnnotation.Stylesheets'>7.27.4 -
Stylesheets</a></h4>
-<div class='topic'><!-- START: 7.27.4 -
juneau-rest-server.HtmlDocAnnotation.Stylesheets -->
+<h4 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HtmlDocAnnotation.Stylesheets'
id='juneau-rest-server.HtmlDocAnnotation.Stylesheets'>7.28.4 -
Stylesheets</a></h4>
+<div class='topic'><!-- START: 7.28.4 -
juneau-rest-server.HtmlDocAnnotation.Stylesheets -->
<p>
The sample root page renders in the default "devops" look-and-feel:
</p>
@@ -19561,13 +19593,13 @@
}
}
</p>
-</div><!-- END: 7.27.4 - juneau-rest-server.HtmlDocAnnotation.Stylesheets -->
-</div><!-- END: 7.27 - juneau-rest-server.HtmlDocAnnotation -->
+</div><!-- END: 7.28.4 - juneau-rest-server.HtmlDocAnnotation.Stylesheets -->
+</div><!-- END: 7.28 - juneau-rest-server.HtmlDocAnnotation -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.DefaultHeaders'
id='juneau-rest-server.DefaultHeaders'>7.28 - Default Headers</a></h3>
-<div class='topic'><!-- START: 7.28 - juneau-rest-server.DefaultHeaders -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.DefaultHeaders'
id='juneau-rest-server.DefaultHeaders'>7.29 - Default Headers</a></h3>
+<div class='topic'><!-- START: 7.29 - juneau-rest-server.DefaultHeaders -->
<p>
The following annotations are provided for specifying default header
values for requests and responses:
</p>
@@ -19609,12 +19641,12 @@
</ul>
</li>
</ul>
-</div><!-- END: 7.28 - juneau-rest-server.DefaultHeaders -->
+</div><!-- END: 7.29 - juneau-rest-server.DefaultHeaders -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.LoggingAndErrorHandling'
id='juneau-rest-server.LoggingAndErrorHandling'>7.29 - Logging and Error
Handling</a></h3>
-<div class='topic'><!-- START: 7.29 -
juneau-rest-server.LoggingAndErrorHandling -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.LoggingAndErrorHandling'
id='juneau-rest-server.LoggingAndErrorHandling'>7.30 - Logging and Error
Handling</a></h3>
+<div class='topic'><!-- START: 7.30 -
juneau-rest-server.LoggingAndErrorHandling -->
<p>
The {@link org.apache.juneau.rest.RestContext#REST_logger} property
allows you to configure
logging for your resource.
@@ -19673,12 +19705,12 @@
<li class='jm'>{@link
org.apache.juneau.rest.RestServlet#log(Level,String,Object...)}
<li class='jm'>{@link
org.apache.juneau.rest.RestServlet#log(Level,Throwable,String,Object...)}
</ul>
-</div><!-- END: 7.29 - juneau-rest-server.LoggingAndErrorHandling -->
+</div><!-- END: 7.30 - juneau-rest-server.LoggingAndErrorHandling -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HttpStatusCodes'
id='juneau-rest-server.HttpStatusCodes'>7.30 - HTTP Status Codes</a></h3>
-<div class='topic'><!-- START: 7.30 - juneau-rest-server.HttpStatusCodes -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.HttpStatusCodes'
id='juneau-rest-server.HttpStatusCodes'>7.31 - HTTP Status Codes</a></h3>
+<div class='topic'><!-- START: 7.31 - juneau-rest-server.HttpStatusCodes -->
<p>
By default, a 200 (OK) status is automatically set as the HTTP status
when a Java method executes
successfully.
@@ -19741,12 +19773,12 @@
<td>The Java method threw an exception other than {@link
org.apache.juneau.rest.RestException}</td>
</tr>
</table>
-</div><!-- END: 7.30 - juneau-rest-server.HttpStatusCodes -->
+</div><!-- END: 7.31 - juneau-rest-server.HttpStatusCodes -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.OverloadingHttpMethods'
id='juneau-rest-server.OverloadingHttpMethods'>7.31 - Overloading HTTP
Methods</a></h3>
-<div class='topic'><!-- START: 7.31 -
juneau-rest-server.OverloadingHttpMethods -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.OverloadingHttpMethods'
id='juneau-rest-server.OverloadingHttpMethods'>7.32 - Overloading HTTP
Methods</a></h3>
+<div class='topic'><!-- START: 7.32 -
juneau-rest-server.OverloadingHttpMethods -->
<p>
Through the use of the built-in <l>"method"</l> GET parameter, you can
implement requests beyond the basic
REST http method types.
@@ -19770,12 +19802,12 @@
allowedMethodParams=<js>"BAR"</js>
)
</p>
-</div><!-- END: 7.31 - juneau-rest-server.OverloadingHttpMethods -->
+</div><!-- END: 7.32 - juneau-rest-server.OverloadingHttpMethods -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.BuiltInParameters'
id='juneau-rest-server.BuiltInParameters'>7.32 - Built-in Parameters</a></h3>
-<div class='topic'><!-- START: 7.32 - juneau-rest-server.BuiltInParameters -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.BuiltInParameters'
id='juneau-rest-server.BuiltInParameters'>7.33 - Built-in Parameters</a></h3>
+<div class='topic'><!-- START: 7.33 - juneau-rest-server.BuiltInParameters -->
<p>
The following URL parameters have special meaning and can be passed in
through the URL of the request:
</p>
@@ -19835,12 +19867,12 @@
</td>
</tr>
</table>
-</div><!-- END: 7.32 - juneau-rest-server.BuiltInParameters -->
+</div><!-- END: 7.33 - juneau-rest-server.BuiltInParameters -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.CustomSerializersAndParsers'
id='juneau-rest-server.CustomSerializersAndParsers'>7.33 - Custom Serializers
and Parsers</a></h3>
-<div class='topic'><!-- START: 7.33 -
juneau-rest-server.CustomSerializersAndParsers -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.CustomSerializersAndParsers'
id='juneau-rest-server.CustomSerializersAndParsers'>7.34 - Custom Serializers
and Parsers</a></h3>
+<div class='topic'><!-- START: 7.34 -
juneau-rest-server.CustomSerializersAndParsers -->
<p>
A very easy-to-use API is provided for defining your own serializers
and parsers at both the servlet and
method levels.
@@ -19961,12 +19993,12 @@
}
}
</p>
-</div><!-- END: 7.33 - juneau-rest-server.CustomSerializersAndParsers -->
+</div><!-- END: 7.34 - juneau-rest-server.CustomSerializersAndParsers -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.UsingWithOsgi'
id='juneau-rest-server.UsingWithOsgi'>7.34 - Using with OSGi</a></h3>
-<div class='topic'><!-- START: 7.34 - juneau-rest-server.UsingWithOsgi -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.UsingWithOsgi'
id='juneau-rest-server.UsingWithOsgi'>7.35 - Using with OSGi</a></h3>
+<div class='topic'><!-- START: 7.35 - juneau-rest-server.UsingWithOsgi -->
<p>
Since REST servlets are basically just <l>HttpServlets</l>,
incorporating them into an OSGi environment
is pretty straightforward.
@@ -20028,12 +20060,12 @@
}
}
</p>
-</div><!-- END: 7.34 - juneau-rest-server.UsingWithOsgi -->
+</div><!-- END: 7.35 - juneau-rest-server.UsingWithOsgi -->
<!--
====================================================================================================
-->
-<h3 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.UnitTesting' id='juneau-rest-server.UnitTesting'>7.35
- Serverless Unit Testing</a></h3>
-<div class='topic'><!-- START: 7.35 - juneau-rest-server.UnitTesting -->
+<h3 class='topic new' onclick='toggle(this)'><a
href='#juneau-rest-server.UnitTesting' id='juneau-rest-server.UnitTesting'>7.36
- Serverless Unit Testing</a></h3>
+<div class='topic'><!-- START: 7.36 - juneau-rest-server.UnitTesting -->
<p>
The {@link org.apache.juneau.rest.mock.MockRest} class is a simple yet
powerful interface for creating serverless
unit tests for your REST interfaces.
@@ -20216,12 +20248,12 @@
client-side request and populating the {@link
org.apache.juneau.rest.mock.MockServletRequest} and {@link
org.apache.juneau.rest.mock.MockServletResponse} objects
directly without involving any sockets.
</p>
-</div><!-- END: 7.35 - juneau-rest-server.UnitTesting -->
+</div><!-- END: 7.36 - juneau-rest-server.UnitTesting -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.Injection' id='juneau-rest-server.Injection'>7.36 -
Using with Spring and Injection frameworks</a></h3>
-<div class='topic'><!-- START: 7.36 - juneau-rest-server.Injection -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.Injection' id='juneau-rest-server.Injection'>7.37 -
Using with Spring and Injection frameworks</a></h3>
+<div class='topic'><!-- START: 7.37 - juneau-rest-server.Injection -->
<p>
The Juneau REST server API is compatible with dependency injection
frameworks such as Spring.
</p>
@@ -20323,24 +20355,24 @@
<jk>this</jk>.<jf>bean3</jf> = bean3;
}
</p>
-</div><!-- END: 7.36 - juneau-rest-server.Injection -->
+</div><!-- END: 7.37 - juneau-rest-server.Injection -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a href='#juneau-rest-server.HTTP2'
id='juneau-rest-server.HTTP2'>7.37 - Using HTTP/2 features</a></h3>
-<div class='topic'><!-- START: 7.37 - juneau-rest-server.HTTP2 -->
+<h3 class='topic ' onclick='toggle(this)'><a href='#juneau-rest-server.HTTP2'
id='juneau-rest-server.HTTP2'>7.38 - Using HTTP/2 features</a></h3>
+<div class='topic'><!-- START: 7.38 - juneau-rest-server.HTTP2 -->
<p>
Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
whenever needed.
<br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
specification.
</p>
-</div><!-- END: 7.37 - juneau-rest-server.HTTP2 -->
+</div><!-- END: 7.38 - juneau-rest-server.HTTP2 -->
<!--
====================================================================================================
-->
-<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.OtherNotes' id='juneau-rest-server.OtherNotes'>7.38 -
Other Notes</a></h3>
-<div class='topic'><!-- START: 7.38 - juneau-rest-server.OtherNotes -->
+<h3 class='topic ' onclick='toggle(this)'><a
href='#juneau-rest-server.OtherNotes' id='juneau-rest-server.OtherNotes'>7.39 -
Other Notes</a></h3>
+<div class='topic'><!-- START: 7.39 - juneau-rest-server.OtherNotes -->
<ul class='spaced-list'>
<li>
Subclasses can use either {@link
javax.servlet.http.HttpServlet#init(ServletConfig)}
@@ -20351,7 +20383,7 @@
For example, to add a <l>"Refresh: 1"</l> header to the
response to auto-refresh a page, the following
parameter can be specified:
<l>"/sample?X-Response-Headers={Refresh=1}"</l>
</ul>
-</div><!-- END: 7.38 - juneau-rest-server.OtherNotes -->
+</div><!-- END: 7.39 - juneau-rest-server.OtherNotes -->
</div><!-- END: 7 - juneau-rest-server -->
<!--
====================================================================================================
-->
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/03.Instantiation/02.BasicRestServlet.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/03.Instantiation/02.BasicRestServlet.html
index 3eaf13f..6d4872a 100644
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/03.Instantiation/02.BasicRestServlet.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/03.Instantiation/02.BasicRestServlet.html
@@ -51,8 +51,8 @@ BasicRestServlet
<jd>/**
* [OPTIONS /*] - Show resource options.
*
- * @param req The HTTP request.
- * @return A bean containing the contents for the OPTIONS page.
+ * <ja>@param</ja> req The HTTP request.
+ * <ja>@return</ja> A bean containing the contents for the
OPTIONS page.
*/</jd>
<ja>@RestMethod</ja>(name=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/01.RestInfoProvider.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider.html
similarity index 99%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/01.RestInfoProvider.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider.html
index 1d3716f..a6e658f 100644
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/01.RestInfoProvider.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-RestInfoProvider
+{updated} RestInfoProvider
<p>
The {@link oajr.RestInfoProvider} class is used to find the title
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider/01.BasicRestInfoProvider.html
similarity index 68%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider/01.BasicRestInfoProvider.html
index 9614bd4..a304fd4 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.RestInfoProvider/01.BasicRestInfoProvider.html
@@ -13,11 +13,22 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{updated} BasicRestInfoProvider
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ The {@link oajr.BasicRestInfoProvider} class is the default
implementation of the
+ {@link oajr.RestInfoProvider} interface.
+</p>
+<p>
+ It finds and collects information gathered from the following locations:
+</p>
+<ul>
+ <li>Localized JSON Swagger files in the classpath.
+ <li>Reflection.
+ <li>Annotations.
+ <li>Properties files.
+</ul>
+<p>
+ The class itself is designed to be extended if you wish to rely mostly
on the default behavior, but tweak
+ certain aspects.
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger.html
deleted file mode 100644
index 01c8f9b..0000000
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger.html
+++ /dev/null
@@ -1,363 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright
ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied. See the License for the
- * specific language governing permissions and limitations under the License.
-
***************************************************************************************************************************/
- -->
-
-{todo} Swagger
-
-<p>
- One of the most useful features of Juneau is the ability to generate
Swagger-based OPTIONS pages for self-documenting designs
- (i.e. REST interfaces that document themselves).
-</p>
-<p>
- As described previously, the <code>PetStore</code> example provides an
example of auto-generated Swagger JSON:
-</p>
-<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.1.png'>
-<p>
- Using {@link oaj.dto.swagger.ui.SwaggerUI}, we're able to render that
JSON as a Swagger user interface:
-</p>
-<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.2.png'>
-<p>
- Any subclass of {@link oajr.BasicRestServlet} gets an auto-generated
Swagger UI when performing an <code>OPTIONS</code>
- request with <code>Accept: text/html</code>.
-</p>
-<p>
- The underlying mechanics are simple.
- The {@link oajr.BasicRestServlet#getOptions(RestRequest)} method
returns a {@link oaj.dto.swagger.Swagger} bean
- consisting of information gathered from annotations and other sources.
- Then that bean is swapped for a {@link oaj.dto.swagger.ui.SwaggerUI}
bean when rendered as HTML.
-</p>
-<p>
- Here's the class that defines the behavior:
-</p>
-<p class='bpcode w800'>
- <ja>@RestResource</ja>(
-
- <jc>// Allow OPTIONS requests to be simulated using
?method=OPTIONS query parameter.</jc>
- allowedMethodParams=<js>"OPTIONS"</js>,
-
- ...
- )
- <jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {
-
- <jd>/**
- * [OPTIONS /*] - Show resource options.
- *
- * <ja>@param</ja> req The HTTP request.
- * <ja>@return</ja> A bean containing the contents for the
OPTIONS page.
- */</jd>
- <ja>@RestMethod</ja>(name=OPTIONS, path=<js>"/*"</js>,
-
- summary=<js>"Swagger documentation"</js>,
- description=<js>"Swagger documentation for this
resource."</js>,
-
- htmldoc=<ja>@HtmlDoc</ja>(
- <jc>// Override the nav links for the swagger
page.</jc>
- navlinks={
- <js>"back: servlet:/"</js>,
- <js>"json:
servlet:/?method=OPTIONS&Accept=text/json&plainText=true"</js>
- },
- <jc>// Never show aside contents of page
inherited from class.</jc>
- aside=<js>"NONE"</js>
- ),
-
- <jc>// POJO swaps to apply to all
serializers/parsers.</jc>
- pojoSwaps={
- <jc>// Use the SwaggerUI swap when rendering
Swagger beans.</jc>
- <jc>// This is a per-media-type swap that only
applies to text/html requests.</jc>
- SwaggerUI.<jk>class</jk>
- },
-
- <jc>// Properties to apply to all serializers/parsers
and REST-specific API objects.</jc>
- properties={
- <jc>// Add descriptions to the following types
when not specified:</jc>
-
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addDescriptionsTo</jsf>,
value=<js>"bean,collection,array,map,enum"</js>),
-
- <jc>// Add x-example to the following
types:</jc>
-
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addExamplesTo</jsf>,
value=<js>"bean,collection,array,map"</js>),
-
- <jc>// Don't generate schema information on the
Swagger bean itself or HTML beans.</jc>
-
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_ignoreTypes</jsf>,
value=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>)
- },
-
- <jc>// Shortcut for boolean properties.</jc>
- flags={
- <jc>// Use $ref references for bean definitions
to reduce duplication in Swagger.</jc>
- <jsf>JSONSCHEMA_useBeanDefs</jsf>
- }
- )
- <jk>public</jk> Swagger getOptions(RestRequest req) {
- <jc>// Localized Swagger for this resource is available
through the RestRequest object.</jc>
- <jk>return</jk> req.getSwagger();
- }
- }
-</p>
-<p>
- Let's look at the various parts of the <code>Petstore</code>
application Swagger UI to see how they are defined.
-</p>
-
-<h5 class='topic'>General Information</h5>
-<p>
- The top part of the page shows general information about the REST
interface:
-</p>
-<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.3.png'>
-<p>
- The information is pulled from the {@link
oajr.annotation.RestResource#swagger() @RestResource(swagger)} annotation.
-</p>
-<h5
class='figure'>org.apache.juneau.examples.rest.petstore.PetStoreResource</h5>
-<p class='bpcode w800'>
- <ja>@RestResource</ja>(
- path=<js>"/petstore"</js>,
- title=<js>"Petstore application"</js>,
- ...
- swagger=@ResourceSwagger(<js>"$F{PetStoreResource.json}"</js>),
- ...
- )
- <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
-</p>
-<p>
- In this particular case, the Swagger is pulled in from a localized
Swagger JSON file located in the
- <code>org.apache.juneau.examples.rest.petstore</code> package using the
{@link oajr.vars.FileVar $F} variable.
-</p>
-<h5 class='figure'>PetStoreResource.json</h5>
-<p class='bpcode w800'>
- {
- <jok>"swagger"</jok>: <jov>"2.0"</jov>,
- <jok>"info"</jok>: {
- <jok>"version"</jok>: <jov>"1.0.0"</jov>,
- <jok>"title"</jok>: <jov>"Swagger Petstore"</jov>,
- <jok>"termsOfService"</jok>: <jov>"You are on your
own."</jov>,
- <jok>"contact"</jok>: {
- <jok>"name"</jok>: <jov>"Juneau Development
Team"</jov>,
- <jok>"email"</jok>:
<jov>"d...@juneau.apache.org"</jov>,
- <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
- },
- <jok>"license"</jok>: {
- <jok>"name"</jok>: <jov>"Apache 2.0"</jov>,
- <jok>"url"</jok>:
<jov>"http://www.apache.org/licenses/LICENSE-2.0.html";</jov>
- }
- },
- <jok>"externalDocs"</jok>: {
- <jok>"description"</jok>: <jov>"Find out more about
Juneau"</jov>,
- <jok>"url"</jok>: <jov>"http://juneau.apache.org";</jov>
- },
- ...
- }
-</p>
-<p>
- Note that the {@link oajr.vars.FileVar $F} variable allows for
request-locale-sensitive name matching so that you can provide
- localized Swagger information.
-</p>
-<p>
- The {@link oajr.vars.FileVar $F} variable simply expands to a string to
fill the {@link oajr.annotation.ResourceSwagger#value() @ResourceSwagger(value)}
- annotation.
- You could equivalently embed JSON directly into your annotation like so:
-</p>
-<p class='bpcode w800'>
- <ja>@RestResource</ja>(
- path=<js>"/petstore"</js>,
- title=<js>"Petstore application"</js>,
- ...
- swagger=<ja>@ResourceSwagger</ja>(
- <js>"{"</js>,
- <js>"swagger: '2.0',"</js>,
- <js>"version: '1.0.0',",</js>,
- ...
- <js>"}"</js>
- ),
- ...
- )
- <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
-</p>
-<p>
- However, a more typical scenario is to define all of your Swagger as
annotations:
-</p>
-<p class='bpcode w800'>
- <ja>@RestResource</ja>(
- path=<js>"/petstore"</js>,
- title=<js>"Petstore application"</js>,
- ...
- swagger=<ja>@ResourceSwagger</ja>(
- version=<js>"1.0.0"</js>,
- title=<js>"Swagger Petstore"</js>,
- termsOfService=<js>"You are on your own."</js>,
- contact=<ja>@Contact</ja>(
- name=<js>"Juneau Development Team"</js>,
- email=<js>"d...@juneau.apache.org"</js>,
- url=<js>"http://juneau.apache.org";</js>
- ),
- license=<ja>@License</ja>(
- name=<js>"Apache 2.0"</js>,
-
url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>
- ),
- externalDocs=<ja>@ExternalDocs</ja>(
- description=<js>"Find out more about
Juneau"</js>,
- url=<js>"http://juneau.apache.org";</js>
- )
- ),
- ...
- )
- <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
-</p>
-<p>
- All annotations support {@doc DefaultRestSvlVariables SVL variables},
so you could for example
- pull localized strings from resource bundles using {@link
oajr.vars.LocalizationVar $L} variables.
-</p>
-<p class='bpcode w800'>
- <ja>@RestResource</ja>(
- path=<js>"/petstore"</js>,
- title=<js>"Petstore application"</js>,
- messages=<js>"nls/MyMessages"</js>,
- ...
- swagger=<ja>@ResourceSwagger</ja>(
- version=<js>"1.0.0"</js>,
- title=<js>"$L{myTitle}"</js>,
- termsOfService=<js>"$L{myTermsOfService}"</js>,
- contact=<ja>@Contact</ja>(
- name=<js>"$L{myTeam}"</js>,
- email=<js>"d...@juneau.apache.org"</js>,
- url=<js>"http://juneau.apache.org";</js>
- ),
- license=<ja>@License</ja>(
- name=<js>"Apache 2.0"</js>,
-
url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>
- ),
- externalDocs=<ja>@ExternalDocs</ja>(
-
description=<js>"$L{myExternalDocsDescription}"</js>,
- url=<js>"http://juneau.apache.org";</js>
- )
- ),
- ...
- )
- <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
-</p>
-<p>
- A third option is to define your Swagger information in your {@link
oajr.annotation.RestResource#messages @RestResource(messages)} resource
- bundle using predefined Swagger keywords:
-</p>
-<p class='bpcode w800'>
- <mk>PetStoreResource.version</mk> = <mv>1.0.0</mv>
- <mk>PetStoreResource.title</mk> = <mv>Swagger Petstore</mv>
- <mk>PetStoreResource.termsOfService</mk> = <mv>You are on your own.</mv>
- <mk>PetStoreResource.contact</mk> = <mv>{name:'Juneau Development
Team', email:'d...@juneau.apache.org',...}</mv>
- <mk>PetStoreResource.license</mk> = <mv>{name:'Apache 2.0',...}</mv>
- <mk>PetStoreResource.externalDocs</mk> = <mv>{description:'Find out
more about Juneau',...}</mv>
-</p>
-<p>
- Information defined in multiple locations are merged into a single set
of data.
- When the same information is provided in multiple locations, the
following order-of-precedence is used:
-</p>
-<ol>
- <li>Java annotations
- <li>Resource bundle
- <li>Swagger JSON file
-</ol>
-
-<h5 class='topic'>Tags</h5>
-<p>
- Tags allow you to group operations into general categories.
- In the user interface, these can be expanded/collapsed by clicking on
the tag sections.
- <br>In the example below, the <code>pet</code> and <code>store</code>
tag sections are collapsed
- and the <code>user</code> section is not:
-</p>
-<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.4.png'>
-<p>
- Tags are also defined in the <ja>@ResourceSwagger</ja> annotation
-</p>
-<h5 class='figure'>PetStoreResource.json</h5>
-<p class='bpcode w800'>
- <jok>"tags"</jok>: [
- {
- <jok>"name"</jok>: <jov>"pet"</jov>,
- <jok>"description"</jok>: <jov>"Everything about your
Pets"</jov>,
- <jok>"externalDocs"</jok>: {
- <jok>"description"</jok>: <jov>"Find out
more"</jov>,
- <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
- }
- },
- {
- <jok>"name"</jok>: <jov>"store"</jov>,
- <jok>"description"</jok>: <jov>"Access to Petstore
orders"</jov>
- },
- {
- <jok>"name"</jok>: <jov>"user",
- <jok>"description"</jok>: <jov>"Operations about
user"</jov>,
- <jok>"externalDocs"</jok>: {
- <jok>"description"</jok>: <jov>"Find out more
about our store"</jov>,
- <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
- }
- }
- ],
-
-</p>
-<p>
- The annotation-only approach is shown here:
-</p>
-<h5
class='figure'>org.apache.juneau.examples.rest.petstore.PetStoreResource</h5>
-<p class='bpcode w800'>
- swagger=<ja>@ResourceSwagger</ja>(
- ...
- tags={
- <ja>@Tag</ja>(
- name=<js>"pet"</js>,
- description=<js>"Everything about your
Pets"</js>,
- externalDocs=<ja>@ExternalDocs</ja>(
- description=<js>"Find out more"</js>,
- url=<js>"http://juneau.apache.org";</js>
- )
- ),
- <ja>@Tag</ja>(
- name=<js>"store"</js>,
- description=<js>"Access to Petstore orders"</js>
- ),
- <ja>@Tag</ja>(
- name=<js>"user"</js>,
- description=<js>"Operations about user"</js>,
- externalDocs=<ja>@ExternalDocs</ja>(
- description=<js>"Find out more about
our store"</js>,
- url=<js>"http://juneau.apache.org";</js>
- )
- )
- }
- ),
-</p>
-<p>
- Tags are associated with operations using the {@link
oajr.annotation.MethodSwagger#tags() @MethodSwagger(tags)} annotation:
-</p>
-
-<h5 class='figure'>GET /user operation</h5>
-<p class='bpcode w800'>
- <ja>@RestMethod</ja>(
- name=<jsf>GET</jsf>,
- path=<js>"/user"</js>,
- summary=<js>"Petstore users"</js>,
- swagger=<ja>@MethodSwagger</ja>(
- tags=<js>"user"</js>
- )
- )
- <jk>public</jk> Collection<User> getUsers() <jk>throws</jk>
NotAcceptable {...}
-</p>
-<p>
- Operations can be mapped to multiple tags.
-</p>
-<p>
- Tags are optional.
- Operations not mapped to tags are listed in the UI before tagged
operations.
-</p>
-<p>
- For example, the <code>getTopPage()</code> method in
<code>PetStoreResource</code> is not tagged,
- as well as the <code>getOptions()</code> method inherited from
<code>BaseRestServlet</code>, so these
- show up at the top of the page:
-</p>
-<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.5.png'>
-
\ No newline at end of file
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/02.BasicRestInfoProvider.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/02.BasicRestInfoProvider.html
deleted file mode 100644
index 1314a0b..0000000
---
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/26.Swagger/02.BasicRestInfoProvider.html
+++ /dev/null
@@ -1,91 +0,0 @@
-<!--
-/***************************************************************************************************************************
- * Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file
- * distributed with this work for additional information regarding copyright
ownership. The ASF licenses this file
- * to you under the Apache License, Version 2.0 (the "License"); you may not
use this file except in compliance
- * with the License. You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an
- * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
or implied. See the License for the
- * specific language governing permissions and limitations under the License.
-
***************************************************************************************************************************/
- -->
-
-BasicRestInfoProvider
-
-<p>
- The {@link oajr.BasicRestInfoProvider} class is the default
implementation of the
- {@link oajr.RestInfoProvider} interface.
-</p>
-<p>
- It finds and collects information gathered from the following locations:
-</p>
-<ul>
- <li>Localized JSON Swagger files in the classpath.
- <li>Reflection.
- <li> annotations.
- <li>Info provided in properties files.
-</ul>
-<p>
- The class itself is designed to be extended if you wish to rely mostly
on the default behavior, but tweak
- certain aspects.
-</p>
-<p>
- The default provider provides several options for defining Swagger
documentation on your resource:
-</p>
-<ul class='spaced-list'>
- <li>
- Provide nothing.
- <br>You'll still get an auto-generated Swagger doc with
information gather solely through reflection, including methods, parameters,
consumes/produces, etc...
- <li>
- Specify localized JSON Swagger files on your classpath.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- MyResource_ja_JP.json
- </p>
- <li>
- Use {@link oajr.annotation.RestResource#swagger()
@RestResource(swagger)} and {@link oajr.annotation.RestMethod#swagger()
@RestMethod(swagger)}
- annotations on your resource classes and methods.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <ja>@RestMethod</ja>(
- swagger=<js>"{tags:'foo,bar,baz'}</js>
- )
- <jk>public</jk> Object myMethod() {...}
- </p>
- <li>
- Use properties files identified by the {@link
oajr.annotation.RestResource#messages @RestResource(messages)} annotation.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <ck>MyResource.myMethod.tags</ck> = <cv>foo,bar,baz</cv>
- </p>
- <li>
- Use any combination of the above.
- <li>
- Extend the <l>BasicRestInfoProvider</l> and provide customized
behavior.
- <br><h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jc>// Our customized info provider.</jc>
- <jc>// Extend from the default implementation and selectively override
values.</jc>
- <jk>public class</jk> MyRestInfoProvider <jk>extends</jk>
BasicRestInfoProvider {
-
- <jc>// Must provide this constructor!</jc>
- <jk>public</jk> MyRestInfoProvider(RestContext context) {
- <jk>super</jk>(context);
- }
-
- <ja>@Override</ja> <jc>/* RestInfoProvider */</jc>
- <jk>public</jk> Swagger getSwagger(RestRequest req)
<jk>throws</jk> RestException {
- Swagger s = <jk>super</jk>.getSwagger(req);
- <jc>// Made inline modifications to generated
swagger.</jc>
- <jk>return</jk> s;
- }
- }
-
- <jc>// Registered via annotation</jc>
- <ja>@RestResource</ja>(infoProvider=MyRestInfoProvider.<jk>class</jk>)
- <jk>public class</jk> MyResource {...}
- </p>
-</ul>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger.html
similarity index 63%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger.html
index 9614bd4..e0aac3a 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++ b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger.html
@@ -13,11 +13,19 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{new} Swagger
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ One of the most useful features of Juneau is the ability to generate
Swagger-based OPTIONS pages for self-documenting designs
+ (i.e. REST interfaces that document themselves).
</p>
+<p>
+ As described previously, the <code>PetStore</code> example provides an
example of auto-generated Swagger JSON:
+</p>
+<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.1.png'>
+<p>
+ Using {@link oaj.dto.swagger.ui.SwaggerUI}, we're able to render that
JSON as a Swagger user interface:
+</p>
+<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.2.png'>
+
+
\ No newline at end of file
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/01.BasicRestServlet.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/01.BasicRestServlet.html
new file mode 100644
index 0000000..76adda9
--- /dev/null
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/01.BasicRestServlet.html
@@ -0,0 +1,96 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+{new} BasicRestServlet
+
+<p>
+ Any subclass of {@link oajr.BasicRestServlet} gets an auto-generated
Swagger UI when performing an <code>OPTIONS</code>
+ request with <code>Accept:text/html</code>.
+</p>
+<p>
+ The underlying mechanics are simple.
+ The {@link oajr.BasicRestServlet#getOptions(RestRequest)} method
returns a {@link oaj.dto.swagger.Swagger} bean
+ consisting of information gathered from annotations and other sources.
+ Then that bean is swapped for a {@link oaj.dto.swagger.ui.SwaggerUI}
bean when rendered as HTML.
+</p>
+<p>
+ Here's the class that defines the behavior:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+
+ <jc>// Allow OPTIONS requests to be simulated using
?method=OPTIONS query parameter.</jc>
+ allowedMethodParams=<js>"OPTIONS"</js>,
+
+ ...
+ )
+ <jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {
+
+ <jd>/**
+ * [OPTIONS /*] - Show resource options.
+ *
+ * <ja>@param</ja> req The HTTP request.
+ * <ja>@return</ja> A bean containing the contents for the
OPTIONS page.
+ */</jd>
+ <ja>@RestMethod</ja>(name=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
+
+ summary=<js>"Swagger documentation"</js>,
+ description=<js>"Swagger documentation for this
resource."</js>,
+
+ htmldoc=<ja>@HtmlDoc</ja>(
+ <jc>// Override the nav links for the swagger
page.</jc>
+ navlinks={
+ <js>"back: servlet:/"</js>,
+ <js>"json:
servlet:/?method=OPTIONS&Accept=text/json&plainText=true"</js>
+ },
+ <jc>// Never show aside contents of page
inherited from class.</jc>
+ aside=<js>"NONE"</js>
+ ),
+
+ <jc>// POJO swaps to apply to all
serializers/parsers.</jc>
+ pojoSwaps={
+ <jc>// Use the SwaggerUI swap when rendering
Swagger beans.</jc>
+ <jc>// This is a per-media-type swap that only
applies to text/html requests.</jc>
+ SwaggerUI.<jk>class</jk>
+ },
+
+ <jc>// Properties to apply to all serializers/parsers
and REST-specific API objects.</jc>
+ properties={
+ <jc>// Add descriptions to the following types
when not specified:</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addDescriptionsTo</jsf>,
value=<js>"bean,collection,array,map,enum"</js>),
+
+ <jc>// Add x-example to the following
types:</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_addExamplesTo</jsf>,
value=<js>"bean,collection,array,map"</js>),
+
+ <jc>// Don't generate schema information on the
Swagger bean itself or HTML beans.</jc>
+
<ja>@Property</ja>(name=<jsf>JSONSCHEMA_ignoreTypes</jsf>,
value=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>)
+ },
+
+ <jc>// Shortcut for boolean properties.</jc>
+ flags={
+ <jc>// Use $ref references for bean definitions
to reduce duplication in Swagger.</jc>
+ <jsf>JSONSCHEMA_useBeanDefs</jsf>
+ }
+ )
+ <jk>public</jk> Swagger getOptions(RestRequest req) {
+ <jc>// Localized Swagger for this resource is available
through the RestRequest object.</jc>
+ <jk>return</jk> req.getSwagger();
+ }
+ }
+</p>
+<p>
+ Note that to have your resource create Swagger UI, you must either
extend from {@link oajr.BasicRestServlet} or provide
+ your own <ja>@RestMethod</ja>-annotated method that returns a {@link
oaj.dto.swagger.Swagger} object and a {@link oaj.dto.swagger.ui.SwaggerUI} swap.
+</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/02.BasicSwaggerInfo.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/02.BasicSwaggerInfo.html
new file mode 100644
index 0000000..ea83734
--- /dev/null
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/02.BasicSwaggerInfo.html
@@ -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.
+
***************************************************************************************************************************/
+ -->
+
+{new} Basic Swagger Info
+
+<p>
+ Let's look at the various parts of the <code>Petstore</code>
application Swagger UI to see how they are defined.
+</p>
+<p>
+ The top part of the page shows general information about the REST
interface:
+</p>
+<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.3.png'>
+<p>
+ The information is pulled from the {@link
oajr.annotation.RestResource#swagger() @RestResource(swagger)} annotation.
+</p>
+<h5
class='figure'>org.apache.juneau.examples.rest.petstore.PetStoreResource</h5>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ path=<js>"/petstore"</js>,
+ title=<js>"Petstore application"</js>,
+ ...
+ swagger=@ResourceSwagger(<js>"$F{PetStoreResource.json}"</js>),
+ ...
+ )
+ <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
+</p>
+<p>
+ In this particular case, the Swagger is pulled in from a localized
Swagger JSON file located in the
+ <code>org.apache.juneau.examples.rest.petstore</code> package using the
{@link oajr.vars.FileVar $F} variable.
+</p>
+<h5 class='figure'>PetStoreResource.json</h5>
+<p class='bpcode w800'>
+ {
+ <jok>"swagger"</jok>: <jov>"2.0"</jov>,
+ <jok>"info"</jok>: {
+ <jok>"version"</jok>: <jov>"1.0.0"</jov>,
+ <jok>"title"</jok>: <jov>"Swagger Petstore"</jov>,
+ <jok>"termsOfService"</jok>: <jov>"You are on your
own."</jov>,
+ <jok>"contact"</jok>: {
+ <jok>"name"</jok>: <jov>"Juneau Development
Team"</jov>,
+ <jok>"email"</jok>:
<jov>"d...@juneau.apache.org"</jov>,
+ <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
+ },
+ <jok>"license"</jok>: {
+ <jok>"name"</jok>: <jov>"Apache 2.0"</jov>,
+ <jok>"url"</jok>:
<jov>"http://www.apache.org/licenses/LICENSE-2.0.html";</jov>
+ }
+ },
+ <jok>"externalDocs"</jok>: {
+ <jok>"description"</jok>: <jov>"Find out more about
Juneau"</jov>,
+ <jok>"url"</jok>: <jov>"http://juneau.apache.org";</jov>
+ },
+ ...
+ }
+</p>
+<p>
+ Note that the {@link oajr.vars.FileVar $F} variable allows for
request-locale-sensitive name matching so that you can provide
+ localized Swagger information.
+</p>
+<p>
+ The {@link oajr.vars.FileVar $F} variable simply expands to a string to
fill the {@link oajr.annotation.ResourceSwagger#value() @ResourceSwagger(value)}
+ annotation.
+ You could equivalently embed JSON directly into your annotation like so:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ path=<js>"/petstore"</js>,
+ title=<js>"Petstore application"</js>,
+ ...
+ swagger=<ja>@ResourceSwagger</ja>(
+ <jc>// Raw Simplified JSON.</jc>
+ <jc>// Values are concatenated.
+ <js>"{"</js>,
+ <js>"swagger: '2.0',"</js>,
+ <js>"version: '1.0.0',"</js>,
+ ...
+ <js>"}"</js>
+ ),
+ ...
+ )
+ <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
+</p>
+<p>
+ However, a more typical (and less error-prone) scenario is to define
all of your Swagger as annotations:
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ path=<js>"/petstore"</js>,
+ title=<js>"Petstore application"</js>,
+ ...
+ swagger=<ja>@ResourceSwagger</ja>(
+ version=<js>"1.0.0"</js>,
+ title=<js>"Swagger Petstore"</js>,
+ termsOfService=<js>"You are on your own."</js>,
+ contact=<ja>@Contact</ja>(
+ name=<js>"Juneau Development Team"</js>,
+ email=<js>"d...@juneau.apache.org"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ ),
+ license=<ja>@License</ja>(
+ name=<js>"Apache 2.0"</js>,
+
url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>
+ ),
+ externalDocs=<ja>@ExternalDocs</ja>(
+ description=<js>"Find out more about
Juneau"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ )
+ ),
+ ...
+ )
+ <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
+</p>
+<p>
+ All annotations support {@doc DefaultRestSvlVariables SVL variables},
so you could for example
+ pull localized strings from resource bundles using {@link
oajr.vars.LocalizationVar $L} variables.
+</p>
+<p class='bpcode w800'>
+ <ja>@RestResource</ja>(
+ path=<js>"/petstore"</js>,
+ title=<js>"Petstore application"</js>,
+ messages=<js>"nls/MyMessages"</js>,
+ ...
+ swagger=<ja>@ResourceSwagger</ja>(
+ version=<js>"1.0.0"</js>,
+ title=<js>"$L{myTitle}"</js>,
+ termsOfService=<js>"$L{myTermsOfService}"</js>,
+ contact=<ja>@Contact</ja>(
+ name=<js>"$L{myTeam}"</js>,
+ email=<js>"d...@juneau.apache.org"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ ),
+ license=<ja>@License</ja>(
+ name=<js>"Apache 2.0"</js>,
+
url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html";</js>
+ ),
+ externalDocs=<ja>@ExternalDocs</ja>(
+
description=<js>"$L{myExternalDocsDescription}"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ )
+ ),
+ ...
+ )
+ <jk>public class</jk> PetStoreResource <jk>extends</jk>
BasicRestServletJena {...}
+</p>
+<p>
+ A third option is to define your Swagger information in your {@link
oajr.annotation.RestResource#messages @RestResource(messages)} resource
+ bundle using predefined Swagger keywords:
+</p>
+<p class='bpcode w800'>
+ <mk>PetStoreResource.version</mk> = <mv>1.0.0</mv>
+ <mk>PetStoreResource.title</mk> = <mv>Swagger Petstore</mv>
+ <mk>PetStoreResource.termsOfService</mk> = <mv>You are on your own.</mv>
+ <mk>PetStoreResource.contact</mk> = <mv>{name:'Juneau Development
Team', email:'d...@juneau.apache.org',...}</mv>
+ <mk>PetStoreResource.license</mk> = <mv>{name:'Apache 2.0',...}</mv>
+ <mk>PetStoreResource.externalDocs</mk> = <mv>{description:'Find out
more about Juneau',...}</mv>
+</p>
+<p>
+ Information defined in multiple locations are merged into a single set
of data.
+ When the same information is provided in multiple locations, the
following order-of-precedence is used:
+</p>
+<ol>
+ <li>Java annotations
+ <li>Resource bundle
+ <li>Swagger JSON file
+</ol>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/03.Tags.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/03.Tags.html
new file mode 100644
index 0000000..bd26f86
--- /dev/null
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/03.Tags.html
@@ -0,0 +1,113 @@
+<!--
+/***************************************************************************************************************************
+ * 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.
+
***************************************************************************************************************************/
+ -->
+
+{new} Tags
+
+<p>
+ Tags allow you to group operations into general categories.
+ In the user interface, these can be expanded/collapsed by clicking on
the tag sections.
+ <br>In the example below, the <code>pet</code> and <code>store</code>
tag sections are collapsed
+ and the <code>user</code> section is not:
+</p>
+<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.4.png'>
+<p>
+ Tags are also defined in the <ja>@ResourceSwagger</ja> annotation
+</p>
+<h5 class='figure'>PetStoreResource.json</h5>
+<p class='bpcode w800'>
+ <jok>"tags"</jok>: [
+ {
+ <jok>"name"</jok>: <jov>"pet"</jov>,
+ <jok>"description"</jok>: <jov>"Everything about your
Pets"</jov>,
+ <jok>"externalDocs"</jok>: {
+ <jok>"description"</jok>: <jov>"Find out
more"</jov>,
+ <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
+ }
+ },
+ {
+ <jok>"name"</jok>: <jov>"store"</jov>,
+ <jok>"description"</jok>: <jov>"Access to Petstore
orders"</jov>
+ },
+ {
+ <jok>"name"</jok>: <jov>"user",
+ <jok>"description"</jok>: <jov>"Operations about
user"</jov>,
+ <jok>"externalDocs"</jok>: {
+ <jok>"description"</jok>: <jov>"Find out more
about our store"</jov>,
+ <jok>"url"</jok>:
<jov>"http://juneau.apache.org";</jov>
+ }
+ }
+ ],
+
+</p>
+<p>
+ The annotation-only approach is shown here:
+</p>
+<h5
class='figure'>org.apache.juneau.examples.rest.petstore.PetStoreResource</h5>
+<p class='bpcode w800'>
+ swagger=<ja>@ResourceSwagger</ja>(
+ ...
+ tags={
+ <ja>@Tag</ja>(
+ name=<js>"pet"</js>,
+ description=<js>"Everything about your
Pets"</js>,
+ externalDocs=<ja>@ExternalDocs</ja>(
+ description=<js>"Find out more"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ )
+ ),
+ <ja>@Tag</ja>(
+ name=<js>"store"</js>,
+ description=<js>"Access to Petstore orders"</js>
+ ),
+ <ja>@Tag</ja>(
+ name=<js>"user"</js>,
+ description=<js>"Operations about user"</js>,
+ externalDocs=<ja>@ExternalDocs</ja>(
+ description=<js>"Find out more about
our store"</js>,
+ url=<js>"http://juneau.apache.org";</js>
+ )
+ )
+ }
+ ),
+</p>
+<p>
+ Tags are associated with operations using the {@link
oajr.annotation.MethodSwagger#tags() @MethodSwagger(tags)} annotation:
+</p>
+
+<h5 class='figure'>GET /user operation</h5>
+<p class='bpcode w800'>
+ <ja>@RestMethod</ja>(
+ name=<jsf>GET</jsf>,
+ path=<js>"/user"</js>,
+ summary=<js>"Petstore users"</js>,
+ swagger=<ja>@MethodSwagger</ja>(
+ tags=<js>"user"</js>
+ )
+ )
+ <jk>public</jk> Collection<User> getUsers() <jk>throws</jk>
NotAcceptable {...}
+</p>
+<p>
+ Operations can be mapped to multiple tags.
+</p>
+<p>
+ Tags are optional.
+ Operations not mapped to tags are listed in the UI before tagged
operations.
+</p>
+<p>
+ For example, the <code>getTopPage()</code> method in
<code>PetStoreResource</code> is not tagged,
+ as well as the <code>getOptions()</code> method inherited from
<code>BaseRestServlet</code>, so these
+ show up at the top of the page:
+</p>
+<img class='bordered' style='width:900px'
src='doc-files/juneau-rest-server.Swagger.5.png'>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/04.Operations.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/04.Operations.html
index 9614bd4..e14a2ff 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/04.Operations.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Operations
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/05.Parameters.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/05.Parameters.html
index 9614bd4..f3dec36 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/05.Parameters.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Parameters
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/06.ParameterExamples.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/06.ParameterExamples.html
index 9614bd4..904d5b7 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/06.ParameterExamples.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Parameter Examples
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/07.Responses.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/07.Responses.html
index 9614bd4..0d5e4d9 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/07.Responses.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Responses
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/08.ResponseExamples.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/08.ResponseExamples.html
index 9614bd4..6dae56b 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/08.ResponseExamples.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Response Examples
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/09.Models.html
similarity index 80%
copy from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
copy to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/09.Models.html
index 9614bd4..6dae56b 100644
--- a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
+++
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.Swagger/09.Models.html
@@ -13,11 +13,8 @@
***************************************************************************************************************************/
-->
-Using HTTP/2 features
+{todo} Response Examples
<p>
- Juneau is built as a veneer on top of the Servlet API, allowing you to
use low-level Servlet APIs
- whenever needed.
- <br>This allows you to take advantage of the newest HTTP/2 features
implemented in the new Servlet 4.0
- specification.
+ TODO
</p>
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/01.Widgets.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/01.Widgets.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/01.Widgets.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/01.Widgets.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/02.PredefinedWidgets.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/02.PredefinedWidgets.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/02.PredefinedWidgets.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/02.PredefinedWidgets.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/03.UiCustomization.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/03.UiCustomization.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/03.UiCustomization.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/03.UiCustomization.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/04.Stylesheets.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/04.Stylesheets.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/04.Stylesheets.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/04.Stylesheets.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.1.png
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.2.png
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.3.png
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/27.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.HtmlDocAnnotation/doc-files/juneau-rest-server.HtmlDocAnnotation.PredefinedWidgets.4.png
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.DefaultHeaders.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/29.DefaultHeaders.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/28.DefaultHeaders.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/29.DefaultHeaders.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/29.LoggingAndErrorHandling.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/30.LoggingAndErrorHandling.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/29.LoggingAndErrorHandling.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/30.LoggingAndErrorHandling.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/30.HttpStatusCodes.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/31.HttpStatusCodes.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/30.HttpStatusCodes.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/31.HttpStatusCodes.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/31.OverloadingHttpMethods.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/32.OverloadingHttpMethods.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/31.OverloadingHttpMethods.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/32.OverloadingHttpMethods.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/32.BuiltInParameters.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/33.BuiltInParameters.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/32.BuiltInParameters.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/33.BuiltInParameters.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/33.CustomSerializersAndParsers.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/34.CustomSerializersAndParsers.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/33.CustomSerializersAndParsers.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/34.CustomSerializersAndParsers.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/34.UsingWithOsgi.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/35.UsingWithOsgi.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/34.UsingWithOsgi.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/35.UsingWithOsgi.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/35.UnitTesting.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/36.UnitTesting.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/35.UnitTesting.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/36.UnitTesting.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/36.Injection.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.Injection.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/36.Injection.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.Injection.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/38.HTTP2.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/37.HTTP2.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/38.HTTP2.html
diff --git
a/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/38.OtherNotes.html
b/juneau-doc/src/main/resources/Topics/07.juneau-rest-server/39.OtherNotes.html
similarity index 100%
rename from
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/38.OtherNotes.html
rename to
juneau-doc/src/main/resources/Topics/07.juneau-rest-server/39.OtherNotes.html
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
index 2829c4c..1cadb39 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestInfoProvider.java
@@ -43,6 +43,12 @@ public interface RestInfoProvider {
/**
* Returns the localized swagger for the REST resource.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getSwagger()}
+ * </ul>
+ *
* @param req The incoming HTTP request.
* @return
* A new {@link Swagger} instance.
@@ -56,6 +62,14 @@ public interface RestInfoProvider {
/**
* Returns the localized site name of the REST resource.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getSiteName()}
+ * <li><code>$RI{siteName}</code> variable.
+ * <li><code>$R{siteName}</code> variable.
+ * </ul>
+ *
* @param req The current request.
* @return The localized site name of the REST resource, or
<jk>null</jk> if none was found.
* @throws Exception
@@ -67,6 +81,14 @@ public interface RestInfoProvider {
/**
* Returns the localized title of the REST resource.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getResourceTitle()}
+ * <li><code>$RI{title}</code> variable.
+ * <li><code>$R{resourceTitle}</code> variable.
+ * </ul>
+ *
* @param req The current request.
* @return The localized title of the REST resource, or <jk>null</jk>
if none was found.
* @throws Exception
@@ -78,6 +100,14 @@ public interface RestInfoProvider {
/**
* Returns the localized description of the REST resource.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getResourceDescription()}
+ * <li><code>$RI{description}</code> variable.
+ * <li><code>$R{resourceDescription}</code> variable.
+ * </ul>
+ *
* @param req The current request.
* @return The localized description of the REST resource, or
<jk>null</jk> if none was found.
* @throws Exception
@@ -89,6 +119,14 @@ public interface RestInfoProvider {
/**
* Returns the localized summary of the specified java method.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getMethodSummary()}
+ * <li><code>$RI{methodSummary}</code> variable.
+ * <li><code>$R{methodSummary}</code> variable.
+ * </ul>
+ *
* @param method The Java method annotated with {@link RestMethod
@RestMethod}.
* @param req The current request.
* @return The localized summary of the method, or <jk>null</jk> if
none was found.
@@ -101,6 +139,14 @@ public interface RestInfoProvider {
/**
* Returns the localized description of the specified java method on
this servlet.
*
+ * <p>
+ * This object is made available through the following:
+ * <ul>
+ * <li class='jm'>{@link RestRequest#getMethodDescription()}
+ * <li><code>$RI{methodDescription}</code> variable.
+ * <li><code>$R{methodDescription}</code> variable.
+ * </ul>
+ *
* @param method The Java method annotated with {@link RestMethod
@RestMethod}.
* @param req The current request.
* @return The localized description of the method, or <jk>null</jk> if
none was was found.
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/vars/RequestVar.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/vars/RequestVar.java
index 9835918..cc589b7 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/vars/RequestVar.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/vars/RequestVar.java
@@ -40,7 +40,6 @@ import org.apache.juneau.svl.*;
* <li><js>"servletParentURI"</js> - Value returned by {@link
UriContext#getRootRelativeServletPathParent()}
* <li><js>"servletPath"</js> - See {@link RestRequest#getServletPath()}
* <li><js>"servletURI"</js> - See {@link
UriContext#getRootRelativeServletPath()}
- * <li><js>"siteName"</js> - See {@link RestRequest#getSiteName()}
* </ul>
*
* <h5 class='section'>Example:</h5>
