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 fdddbf8 Javadocs
fdddbf8 is described below
commit fdddbf8e4b8b36d748f5b54171a590d1a6d1fc4e
Author: JamesBognar <[email protected]>
AuthorDate: Thu Dec 30 11:55:20 2021 -0500
Javadocs
---
.../06.juneau-rest-server/15.jrs.Swagger.html | 2 +-
.../01.jrs.BasicRestServletSwagger.html | 98 +-
.../15.jrs.Swagger/02.jrs.BasicSwaggerInfo.html | 4 +-
.../15.jrs.Swagger/03.jrs.SwaggerTags.html | 2 +-
.../15.jrs.Swagger/04.jrs.SwaggerOperations.html | 2 +-
.../15.jrs.Swagger/05.jrs.SwaggerParameters.html | 54 +-
.../06.jrs.SwaggerParameterExamples.html | 238 -----
...Responses.html => 06.jrs.SwaggerResponses.html} | 2 +-
...waggerModels.html => 07.jrs.SwaggerModels.html} | 20 +-
.../08.jrs.SwaggerResponseExamples.html | 236 -----
...ylesheet.html => 08.jrs.SwaggerStylesheet.html} | 2 +-
.../16.jrs.ExecutionStatistics.html | 30 +-
.../17.jrs.HtmlDocAnnotation.html | 18 +-
.../01.jrs.HtmlUIvsDI.html | 2 +-
.../02.jrs.HtmlWidgets.html | 40 +-
.../03.jrs.HtmlPredefinedWidgets.html | 79 +-
.../04.jrs.HtmlUiCustomization.html | 123 ++-
.../05.jrs.HtmlStylesheets.html | 41 +-
juneau-doc/src/main/javadoc/overview.html | 1016 +++++---------------
juneau-doc/src/main/javadoc/resources/docs.txt | 4 +-
.../src/main/javadoc/resources/fragments/toc.html | 34 +-
21 files changed, 496 insertions(+), 1551 deletions(-)
diff --git a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger.html
index b9f8f9b..84a880a 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Swagger', flags:'todo'}
+{title:'Swagger'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/01.jrs.BasicRestServletSwagger.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/01.jrs.BasicRestServletSwagger.html
index 06efa43..6b8732a 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/01.jrs.BasicRestServletSwagger.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/01.jrs.BasicRestServletSwagger.html
@@ -13,12 +13,42 @@
***************************************************************************************************************************/
-->
-{title:'BasicRestServlet', updated:'8.1.0', flags:'todo'}
+{title:'BasicRestServlet/BasicRestObject', updated:'8.1.0,9.0.0'}
<div class='topic'>
<p>
- Any subclass of {@link oajr.BasicRestServlet} gets an
auto-generated Swagger UI when performing an <c>OPTIONS</c>
- request with <c>Accept:text/html</c>.
+ Any subclass of {@link oajr.BasicRestServlet} and {@link
oajr.BasicRestObject} gets an auto-generated Swagger UI when performing an
<c>OPTIONS</c>
+ request with <c>Accept:text/html</c> due to the following
method:
+ </p>
+ <p class='bcode w800'>
+ | <ja>@RestGet</ja>(
+ | path=<js>"/api/*"</js>,
+ | summary=<js>"Swagger documentation"</js>,
+ | description=<js>"Swagger documentation for this
resource."</js>
+ | )
+ | <ja>@HtmlDocConfig</ja>(
+ | <jc>// Should override config annotations
defined on class.</jc>
+ | rank=10,
+ | <jc>// Override the nav links for the swagger
page.</jc>
+ | navlinks={
+ | <js>"back: servlet:/"</js>,
+ | <js>"json:
servlet:/?Accept=text/json&plainText=true"</js>
+ | },
+ | <jc>// Never show aside contents of page
inherited from class.</jc>
+ | aside=<js>"NONE"</js>
+ | )
+ | <ja>@BeanConfig</ja>(
+ | <jc>// POJO swaps to apply to all
serializers/parsers on this method.</jc>
+ | swaps={
+ | <jc>// Use the SwaggerUI swap when
rendering Swagger beans.
+ | // This is a per-media-type swap that
only applies to text/html requests.</jc>
+ | SwaggerUI.class
+ | }
+ | )
+ | <ja>@Override</ja> <jc>/* BasicRestOperations */</jc>
+ | <jk>public</jk> Swagger getSwagger(RestRequest
<jv>req</jv>) {
+ | <jk>return</jk>
<jv>req</jv>.getSwagger().orElseThrow(NotFound::<jk>new</jk>);
+ | }
</p>
<p>
The underlying mechanics are simple.
@@ -27,67 +57,7 @@
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='bcode w800'>
- | <ja>@Rest</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>@RestOp</ja>(method=<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>
- | )
- | )
- | <ja>@JsonSchemaConfig</ja>(
- | <jc>// Add descriptions to the
following types when not specified:</jc>
- |
addDescriptionsTo=<js>"bean,collection,array,map,enum"</js>,
- | <jc>// Add x-example to the following
types:</jc>
- |
addExamplesTo=<js>"bean,collection,array,map"</js>,
- | <jc>// Don't generate schema
information on the Swagger bean itself or HTML beans.</jc>
- |
ignoreTypes=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>,
- | <jc>// Use $ref references for bean
definitions to reduce duplication in Swagger.</jc>
- | useBeanDefs=<js>"true"</js>
- | )
- | <ja>@BeanConfig</ja>(
- | <jc>// When parsing generated beans,
ignore unknown properties that may only exist as getters and not setters.</jc>
- |
ignoreUnknownBeanProperties=<js>"true"</js>,
- | <jc>// POJO swaps to apply to all
serializers/parsers on this method.</jc>
- | swaps={
- | <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>
- | }
- | )
- | <jk>public</jk> Swagger getOptions(RestRequest
<jv>req</jv>) {
- | <jc>// Localized Swagger for this
resource is available through the RestRequest object.</jc>
- | <jk>return</jk>
<jv>req</jv>.getSwagger();
- | }
- | }
- </p>
- <p>
- Note that to have your resource create Swagger UI, you must
either extend from {@link oajr.BasicRestServlet} or provide
+ Note that to have your resource create Swagger UI, you must
either extend from one of the basic resource classes or provide
your own <ja>@RestOp</ja>-annotated method that returns a
{@link oaj.dto.swagger.Swagger} object and a {@link
oaj.dto.swagger.ui.SwaggerUI} swap.
</p>
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/02.jrs.BasicSwaggerInfo.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/02.jrs.BasicSwaggerInfo.html
index eda0965..4a52dde 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/02.jrs.BasicSwaggerInfo.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/02.jrs.BasicSwaggerInfo.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Basic Swagger Info', flags:'todo'}
+{title:'Basic Swagger Info', updated:'9.0.0'}
<div class='topic'>
<p>
@@ -82,7 +82,7 @@
| ...
| swagger=<ja>@Swagger</ja>(
| <jc>// Raw Simplified JSON.</jc>
- | <jc>// Values are concatenated.
+ | <jc>// Values are concatenated.</jc>
| <js>"{"</js>,
| <js>"swagger: '2.0',"</js>,
| <js>"version: '1.0.0',"</js>,
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/03.jrs.SwaggerTags.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/03.jrs.SwaggerTags.html
index e6e4d5a..279dc62 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/03.jrs.SwaggerTags.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/03.jrs.SwaggerTags.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Tags', flags:'todo'}
+{title:'Tags'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/04.jrs.SwaggerOperations.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/04.jrs.SwaggerOperations.html
index 0f4e1ed..dc0c161 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/04.jrs.SwaggerOperations.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/04.jrs.SwaggerOperations.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Operations', flags:'todo'}
+{title:'Operations'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/05.jrs.SwaggerParameters.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/05.jrs.SwaggerParameters.html
index 3b08647..eaf9e15 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/05.jrs.SwaggerParameters.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/05.jrs.SwaggerParameters.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Parameters', flags:'todo'}
+{title:'Parameters', updated:'9.0.0'}
<div class='topic'>
<p>
@@ -29,27 +29,29 @@
| <jk>public</jk> Collection<Pet> getPets(
| <ja>@Query</ja>(
| name=<js>"s"</js>,
- | description={
- | <js>"Search."</js>,
- | <js>"Key/value pairs
representing column names and search tokens."</js>,
- | <js>"'*' and '?' can be
used as meta-characters in string fields."</js>,
- | <js>"'>', '>=',
'<', and '<=' can be used as limits on numeric and date fields."</js>,
- | <js>"Date fields can be
matched with partial dates (e.g. '2018' to match any date in the year
2018)."</js>
- | },
- | type=<js>"array"</js>,
- | collectionFormat=<js>"csv"</js>,
- |
example=<js>"Bill*,birthDate>2000"</js>
+ | schema=<ja>@Schema</ja>(
+ | description={
+ |
<js>"Search."</js>,
+ | <js>"Key/value
pairs representing column names and search tokens."</js>,
+ | <js>"'*' and
'?' can be used as meta-characters in string fields."</js>,
+ | <js>"'>',
'>=', '<', and '<=' can be used as limits on numeric and date
fields."</js>,
+ | <js>"Date
fields can be matched with partial dates (e.g. '2018' to match any date in the
year 2018)."</js>
+ | },
+ | type=<js>"array"</js>,
+ |
collectionFormat=<js>"csv"</js>
+ | )
| )
| String[] <jv>s</jv>,
| <ja>@Query</ja>(
| name=<js>"v"</js>,
- | description={
- | <js>"View."</js>,
- | <js>"Column names to
display."</js>
- | },
- | type=<js>"array"</js>,
- | collectionFormat=<js>"csv"</js>,
- |
example=<js>"name,birthDate"</js>
+ | schema=<ja>@Schema</ja>(
+ | description={
+ |
<js>"View."</js>,
+ | <js>"Column
names to display."</js>
+ | },
+ | type=<js>"array"</js>,
+ |
collectionFormat=<js>"csv"</js>
+ | )
| )
| String[] <jv>v</jv>,
| ...
@@ -57,11 +59,13 @@
| ...
| }
</p>
- <p>
- <b>Note:</b> The <c>type</c> and <c>collectionFormat</c>
values above are optional and auto-detected based on the
- parameter class type if omitted. They're included here for
clarity.
- The examples will be explained in the next section.
- </p>
+ <ul class='spaced-list'>
+ <li class='note'>The {@link oaj.http.annotation.Schema @Schema}
annotation can also be attached
+ directly to the parameter or parameter type as well.
+ <li class='note'>The {@link oaj.http.annotation.Schema#type()
type} and {@link oaj.http.annotation.Schema#collectionFormat()
collectionFormat} values above are optional and auto-detected based on the
+ parameter class type if omitted. They're included here
for clarity.
+ The examples will be explained in the next section.
+ </ul>
<p>
Another option is to specify your parameter information in the
<c>parameters</c> annotation as free-form Simple JSON.
In the case of the <c>PetStoreResource.getPets()</c> method, we
pull this information from a static field
@@ -137,7 +141,9 @@
| )
| )
| <jk>public</jk> Ok postPet(
- | <ja>@Body</ja>(description=<js>"Pet
object to add to the store"</js>) PetCreate <jv>pet</jv>
+ | <ja>@Body</ja>
+ | <ja>@Schema</ja>(description=<js>"Pet
object to add to the store"</js>)
+ | PetCreate <jv>pet</jv>
| ) <jk>throws</jk> IdConflict, NotAcceptable,
UnsupportedMediaType {
|
| <jf>store</jf>.create(<jv>pet</jv>);
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerParameterExamples.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerParameterExamples.html
deleted file mode 100644
index 5052f28..0000000
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerParameterExamples.html
+++ /dev/null
@@ -1,238 +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.
-
***************************************************************************************************************************/
- -->
-
-{title:'Parameter Examples', updated:'8.1.0', flags: 'todo'}
-
-<div class='topic'>
- <p>
- The <c>model</c> select box in the parameters can be expanded
to show examples:
- </p>
- <img class='bordered w900' src='doc-files/jrs.Swagger.Parameters.1.png'>
- <p>
- The examples for query/form-data/path/header parameters can be
defined using the <c>example</c> attribute on your annotated parameters as
shown here:
- </p>
- <p class='bcode w800'>
- | <ja>@RestGet</ja>
- | <jk>public</jk> Collection<Pet> getPets(
- | <ja>@Query</ja>(
- | name=<js>"s"</js>,
- | description={
- | <js>"Search."</js>,
- | <js>"Key/value pairs
representing column names and search tokens."</js>,
- | <js>"'*' and '?' can be
used as meta-characters in string fields."</js>,
- | <js>"'>', '>=',
'<', and '<=' can be used as limits on numeric and date fields."</js>,
- | <js>"Date fields can be
matched with partial dates (e.g. '2018' to match any date in the year
2018)."</js>
- | },
- | type=<js>"array"</js>,
- | collectionFormat=<js>"csv"</js>,
- |
example=<js>"Bill*,birthDate>2000"</js>
- | )
- | String[] <jv>query</jv>,
- | ...
- | ) <jk>throws</jk> NotAcceptable {
- | ...
- | }
- </p>
- <p>
- This value gets converted to an <c>x-examples</c> attribute in
your parameter information:
- </p>
- <p class='bcode w800'>
- | {
- | <jok>"swagger"</jok>: <jov>"2.0"</jov>,
- | <jok>"paths"</jok>: {
- | <jok>"/pet"</jok>: {
- | <jok>"get"</jok>: {
- |
<jok>"operationId"</jok>: <jov>"getPets"</jov>,
- | <jok>"summary"</jok>:
<jov>"All pets in the store"</jov>,
- |
<jok>"parameters"</jok>: [
- | {
- |
<jok>"in"</jok>: <jov>"query"</jov>,
- |
<jok>"name"</jok>: <jov>"s"</jov>,
- | ...
- |
<jok>"x-examples"</jok>: {
- |
<jok>"example"</jok>: <jov>"?s=Bill*,birthDate>2000"</jov>
- | }
- | },
- | ...
- </p>
- <p>
- Examples for request bodies includes all supported
<c>Content-Type</c> values:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.Parameters.3.png'>
- <p>
- These are based on the parsers registered on your servlet or
method.
- </p>
- <p>
- Selecting any of the content types shows you a representative
example for the POJO:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.Parameters.4.png'>
- <p>
- There are several options for defining examples for request
bodies:
- </p>
- <ul class='spaced-list'>
- <li>
- {@del oaj.http.annotation.Body#example()
@Body(example)} annotation.
- <li>
- {@del oaj.http.annotation.Body#examples()
@Body(examples)} annotation.
- <li>
- Defining an <js>"x-examples"</js> field in the
inherited Swagger JSON body field (classpath file or
<c><ja>@Swagger</ja>(value)</c>/<c><ja>@OpSwagger</ja>(value)</c>).
- <li>
- Defining an <js>"x-examples"</js> field in the Swagger
Schema Object for the body (including referenced <js>"$ref"</js> schemas).
- <li>
- Allowing Juneau to auto-generate a code example.
- </ul>
- <p>
- When using {@del oaj.http.annotation.Body#example()
@Body(example)}, you specify a Simple JSON representation of your POJO.
- The Swagger generator will then convert that JSON into a POJO
using the registered serializers on the REST method to produce examples for all
- supported language types.
- </p>
-
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- | <jc>// A JSON representation of a PetCreate object.</jc>
- | <ja>@Body</ja>(
- |
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- | )
- </p>
-
- <p>
- The {@del oaj.http.annotation.Body#examples() @Body(examples)}
annotation allows you to specify raw output values per media type.
- This field allows you to override the behavior and show
examples for only specified media types or different examples for different
media types.
- </p>
-
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- | <jc>// A JSON representation of a PetCreate object.</jc>
- | <ja>@Body</ja>(
- | examples={
- |
<js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
- |
<js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
- | }
- | )
- </p>
- <p>
- The Swagger generator uses these to create an <c>x-examples</c>
entry in your generated Swagger:
- </p>
- <p class='bcode w800'>
- | <jok>"/pet"</jok>: {
- | <jok>"post"</jok>: {
- | <jok>"operationId"</jok>:
<jov>"postPet"</jov>,
- | <jok>"summary"</jok>: <jov>"Add a new
pet to the store"</jov>,
- | <jok>"parameters"</jok>: [
- | {
- | <jok>"in"</jok>:
<jov>"body"</jov>,
- |
<jok>"description"</jok>: <jov>"Pet object to add to the store"</jov>,
- | <jok>"required"</jok>:
<jov>true</jov>,
- | <jok>"schema"</jok>: {
- |
<jok>"$ref"</jok>: <jov>"#/definitions/PetCreate"</jov>
- | },
- |
<jok>"x-examples"</jok>: {
- |
<jok>"application/json"</jok>: <jov>"{\n\t\"name\": \"Doggie\",\n\t\"species\":
\"Dog\",\n\t\"price\": 9.99,\n\t\"tags\": [\n..."</jov>,
- |
<jok>"application/json+simple"</jok>: <jov>"{\n\tname: 'Doggie',\n\tspecies:
'Dog',\n\tprice: 9.99,\n\ttags: [\n\t\t'friendly..."</jov>,
- |
<jok>"text/xml"</jok>: <jov>"<?xml version=\"1.0\"
encoding=\"UTF-8\"?>\n<object>\n\t<name>Doggie</name&..."</jov>,
- |
<jok>"text/html+stripped"</jok>:
<jov>"<table>\n\t<tr>\n\t\t<td>name</td>\n\t\t<td>Doggie</t..."</jov>,
- |
<jok>"text/uon"</jok>:
<jov>"(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)"</jov>,
- |
<jok>"application/x-www-form-urlencoded"</jok>:
<jov>"name=Doggie\n&species=Dog\n&price=9.99\n&tags=@(\n\tfriendly,\n\tcute\n)"</jov>,
- |
<jok>"text/openapi"</jok>:
<jov>"(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)"</jov>,
- |
<jok>"octal/msgpack"</jok>: <jov>"84 A4 6E 61 6D 65 A6 44 6F 67 67 69 65 A7 73
70 65 63 69 65 73 A3 44 6F 67 A5 70 72 69 63 6..."</jov>,
- |
<jok>"text/plain"</jok>:
<jov>"{name:'Doggie',species:'Dog',price:9.99,tags:['friendly','cute']}"</jov>,
- |
<jok>"text/xml+rdf"</jok>: <jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"ht..."</jov>,
- |
<jok>"text/turtle"</jok>: <jov>"@prefix jp:
<http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.a...";</jov>,
- |
<jok>"text/n-triple"</jok>: <jov>"_:A59722791X3aX165d321a2b4X3aXX2dX7fca
<http://www.apache.org/juneaubp/name> \"Doggie..."</jov>,
- |
<jok>"text/n3"</jok>: <jov>"@prefix jp:
<http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apach...";</jov>
- | }
- | }
- | ],
- </p>
- <p>
- Another option is to define these directly in your resource
Swagger JSON file, or via {@link oajr.annotation.Rest#swagger()
@Rest(swagger)}/{@link oajr.annotation.RestOp#swagger() @RestOp(swagger)}.
- </p>
- <p>
- Juneau also supports auto-generation of JSON-Schema directly
from POJO classes.
- By default, the generated swagger uses to the {@del
oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- setting to automatically add examples to beans, collections,
arrays, and maps:
- </p>
- <p class='bcode w800'>
- | <jk>public abstract class</jk> BasicRestServlet
<jk>extends</jk> RestServlet <jk>implements</jk> BasicRestConfig {
- |
- | <ja>@RestOp</ja>(method=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
- | ...
- | )
- | <ja>@JsonSchemaConfig</ja>(
- | <jc>// Add x-example to the following
types:</jc>
- |
addExamplesTo=<js>"bean,collection,array,map"</js>,
- | ...
- | )
- | <jk>public</jk> Swagger getOptions(RestRequest
req) {...}
- </p>
- <p>
- Examples can be defined via static methods, fields, and
annotations on the classes themselves.
- </p>
- <h5 class='figure'>Examples:</h5>
- <p class='bcode w800'>
- | <jc>// Annotation on class.</jc>
- |
<ja>@Example</ja>(<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>)
- | <jk>public class</jk> PetCreate {
- | ...
- | }
- </p>
- <p class='bcode w800'>
- <jc>// Annotation on static method.</jc>
- <jk>public class</jk> PetCreate {
- <ja>@Example</ja>
- <jk>public static</jk> PetCreate <jsm>sample</jsm>() {
- <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
- }
- }
- </p>
- <p class='bcode w800'>
- | <jc>// Static method with specific name 'example'.</jc>
- | <jk>public class</jk> PetCreate {
- | <jk>public static</jk> PetCreate
<jsm>example</jsm>() {
- | <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
- | }
- | }
- </p>
- <p class='bcode w800'>
- | <jc>// Static field.</jc>
- | <jk>public class</jk> PetCreate {
- | <ja>@Example</ja>
- | <jk>public static</jk> PetCreate
<jsf>EXAMPLE</jsf> = <jk>new</jk> PetCreate(<js>"Doggie"</js>, 9.99f,
<js>"Dog"</js>, <jk>new</jk> String[] {<js>"friendly"</js>,<js>"cute"</js>});
- | }
- </p>
- <p>
- Examples can also be specified via generic properties as well
using the {@link oaj.BeanContext.Builder#example(Class,Object)} setting or
{@del oaj.annotation.BeanConfig#examples() @BeanConfig(examples)} annotation at
either the class or method level.
- </p>
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- | <jc>// Examples defined at class level.</jc>
- | <ja>@Rest</ja>(...)
- | <ja>@BeanConfig</ja>(
- | examples=<js>"{PetCreate:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}"</js>
- | )
- </p>
- <ul class='seealso'>
- <li class='ja'>{@link oaj.annotation.Example}
- <li class='jc'>{@link oaj.BeanContext.Builder}
- <ul>
- <li class='jf'>{@link
oaj.BeanContext.Builder#example(Class,Object) example(Class,Object)}
- </ul>
- <li class='jc'>{@link oaj.jsonschema.JsonSchemaGenerator}
- <ul>
- <li class='jf'>{@del
oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- <li class='jf'>{@del
oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples
JSONSCHEMA_allowNestedExamples}
- </ul>
- </ul>
-</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerResponses.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerResponses.html
similarity index 98%
rename from
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerResponses.html
rename to
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerResponses.html
index e94017a..c32a401 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerResponses.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/06.jrs.SwaggerResponses.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Responses', flags:'todo'}
+{title:'Responses'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/09.jrs.SwaggerModels.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerModels.html
similarity index 85%
rename from
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/09.jrs.SwaggerModels.html
rename to
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerModels.html
index 8d6e232..8ef2a89 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/09.jrs.SwaggerModels.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/07.jrs.SwaggerModels.html
@@ -13,27 +13,21 @@
***************************************************************************************************************************/
-->
-{title:'Models', flags:'todo'}
+{title:'Models', updated:'9.0.0'}
<div class='topic'>
<p>
- The {@del
oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_useBeanDefs} setting can be used
to reduce the size of your
+ The {@link
oaj.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()} setting can be used
to reduce the size of your
generated Swagger JSON files by creating model definitions for
beans and referencing those definitions through <c>$ref</c> attributes.
</p>
<p>
- By default, this flag is enabled when extending from {@link
oajr.BasicRestServlet}:
+ This setting is disabled by default, but can be set on the
{@link oajr.RestContext.Builder} object:
</p>
<p class='bcode w800'>
- | <jk>public abstract class</jk> BasicRestServlet
<jk>extends</jk> RestServlet <jk>implements</jk> BasicRestConfig {
- |
- | <ja>@RestOp</ja>(method=<jsf>OPTIONS</jsf>,
path=<js>"/*"</js>,
- | ...
- | flags={
- | <jc>// Use $ref references for
bean definitions to reduce duplication in Swagger.</jc>
- |
<jsf>JSONSCHEMA_useBeanDefs</jsf>
- | }
- | )
- | <jk>public</jk> Swagger getOptions(RestRequest
<jv>req</jv>) {...}
+ | <ja>@HookEvent</ja>(<jsf>INIT</jsf>)
+ | <jk>public void</jk> init(RestContext.Builder
<jv>builder</jv>) {
+ |
<jv>builder</jv>.jsonSchemaGenerator().useBeanDefs();
+ | }
</p>
<p>
In the Swagger UI, this causes bean definitions to show up in
the Models section at the bottom of the page:
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerResponseExamples.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerResponseExamples.html
deleted file mode 100644
index d1c4f87..0000000
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerResponseExamples.html
+++ /dev/null
@@ -1,236 +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.
-
***************************************************************************************************************************/
- -->
-
-{title:'Response Examples', flags:'todo'}
-
-<div class='topic'>
- <p>
- The <c>model</c> select box in the responses can be expanded to
show examples:
- </p>
- <h5 class='figure'>PetStoreResource.getPet()</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.1.png'>
- <p>
- Examples are provided for any supported <c>Accept</c> type
based on the serializers defined on your
- servlet/method.
- </p>
- <h5 class='figure'>application/json+simple</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.2.png'>
- <h5 class='figure'>text/uon</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.3.png'>
- <p>
- Examples are pulled from the <c>examples</c> attribute in the
response object of the generated Swagger JSON:
- </p>
- <p class='bcode w800'>
- | <jok>"/pet/{petId}"</jok>: {
- | <jok>"get"</jok>: {
- | <jok>"operationId"</jok>:
<jov>"getPet"</jov>,
- | <jok>"summary"</jok>: <jov>"Find pet by
ID"</jov>,
- | <jok>"description"</jok>: <jov>"Returns
a single pet"</jov>,
- | <jok>"responses"</jok>: {
- | <jok>"200"</jok>: {
- |
<jok>"description"</jok>: <jov>"OK"</jov>,
- | <jok>"schema"</jok>: {
- |
<jok>"$ref"</jok>: <jov>"#/definitions/Pet"</jov>
- | },
- | <jok>"examples"</jok>: {
- |
<jok>"text/html+stripped"</jok>:
<jov>"<table>\n\t<tr>\n\t\t<td>id</td>\n\t\t<td>\t\t\t<a
href=\"..."</jov>,
- |
<jok>"text/html+schema"</jok>: <jov>"<html>\n\t<head>\n\t\t<link
rel='icon' href='$U{servlet:/htdocs/cat.png}'/>..."</jov>,
- |
<jok>"application/json"</jok>: <jov>"{\n\t\"id\": 123,\n\t\"species\":
{\n\t\t\"name\": \"Dog\",\n\t\t\"id\": 123\n\t},\n\t\"name\..."</jov>,
- |
<jok>"application/json+simple"</jok>: <jov>"{\n\tid: 123,\n\tspecies:
{\n\t\tname: 'Dog',\n\t\tid: 123\n\t},\n\tname: 'Doggie',\n\..."</jov>,
- |
<jok>"application/json+schema"</jok>: <jov>"{\n\t\"type\":
\"object\",\n\t\"properties\": {\n\t\t\"id\": {\n\t\t\t\"type\":
\"inte..."</jov>,
- |
<jok>"text/xml"</jok>: <jov>"<?xml version=\"1.0\"
encoding=\"UTF-8\"?>\n<Pet>\n\t<id>123</id>\n\t<spec..."</jov>,
- |
<jok>"text/xml+schema"</jok>: <jov>"<schema
xmlns=\"http://www.w3.org/2001/XMLSchema\";
targetNamespace=\"http://www.apache.org/...";</jov>,
- |
<jok>"text/uon"</jok>:
<jov>"(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\t\tn..."</jov>,
- |
<jok>"application/x-www-form-urlencoded"</jok>:
<jov>"id=123\n&species=(\n\tname=Dog,\n\tid=123\n)\n&name=Doggie\n&tags=@(\n\t(\n\..."</jov>,
- |
<jok>"text/openapi"</jok>:
<jov>"(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\..."</jov>,
- |
<jok>"octal/msgpack"</jok>: <jov>"86 A2 69 64 7B A7 73 70 65 63 69 65 73 82 A4
6E 61 6D 65 A3 44 6F 67 A2 69 64 7B A4 6E 61 6D 65 ..."</jov>,
- |
<jok>"text/xml+soap"</jok>: <jov>"<?xml version=\"1.0\"
encoding=\"UTF-8\"?>\n<Envelope
soap=\"http://www.w3.org/2003/05/...";</jov>,
- |
<jok>"text/plain"</jok>:
<jov>"{id:123,species:{name:'Dog',id:123},name:'Doggie',tags:[{name:'MyTag',id:123}],price:0.0,status:'AV..."</jov>,
- |
<jok>"text/xml+rdf"</jok>: <jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"http://...";</jov>,
- |
<jok>"text/xml+rdf+abbrev"</jok>: <jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"..."</jov>,
- |
<jok>"text/turtle"</jok>: <jov>"@prefix jp:
<http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apache...";</jov>,
- |
<jok>"text/n-triple"</jok>: <jov>"_:A720f0f4fX3aX165d4974933X3aXX2dX7f93
<http://www.apache.org/juneaubp/name> \"Dog\" .\n_:..."</jov>,
- |
<jok>"text/n3"</jok>: <jov>"@prefix jp:
<http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apache.org...";</jov>
- </p>
- <p>
- There are several options for defining examples for response
bodies:
- </p>
- <ul class='spaced-list'>
- <li>
- {@del oaj.http.annotation.Response#example()
@Response(example)} annotation.
- <li>
- {@link oaj.http.annotation.Response#examples()
@Response(examples)} annotation.
- <li>
- Defining an <js>"examples"</js> field in the inherited
Swagger JSON response object (classpath file or
<c><ja>@Swagger</ja>(value)</c>/<c><ja>@OpSwagger</ja>(value)</c>).
- <li>
- Defining an <js>"examples"</js> field in the Swagger
Schema Object for the response object (including referenced <js>"$ref"</js>
schemas).
- <li>
- Allowing Juneau to auto-generate a code example.
- </ul>
-
- <p>
- The {@del oaj.http.annotation.Response#example
@Response(example)} annotation can be used on either your
<ja>@RestOp</ja>-annotated
- method or return class to define the example of the body.
- </p>
- <p class='bcode w800'>
- | <jc>// A JSON representation of a Pet object.</jc>
- | <ja>@Response</ja>(
- |
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- | )
- </p>
- <p>
- This is a Simple JSON representation of the body that is
converted to a POJO and then serialized to all the registered serializers on
the REST method to produce examples for all
- supported language types.
- These values are then used to automatically populate the
<c>examples</c> field.
- </p>
- <p>
- Direct per-media-type examples can also be defined using the
{@link oaj.http.annotation.Response#examples @Response(examples)} annotation:
- </p>
- <p class='bcode w800'>
- | <jc>// A JSON representation of a PetCreate object.</jc>
- | <ja>@Response</ja>(
- | examples={
- |
<js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
- |
<js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
- | }
- | )
- </p>
-
- <p>
- Juneau also supports auto-generation of JSON-Schema directly
from POJO classes.
- By default, the generated swagger uses to the {@del
oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- setting to automatically add examples to beans, collections,
arrays, and maps:
- </p>
- <p>
- In particular, examples can be defined via static methods,
fields, and annotations on the classes themselves.
- </p>
- <p class='bcode w800'>
- | <jc>// Annotation on class.</jc>
- |
<ja>@Example</ja>(<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>)
- | <jk>public class</jk> PetCreate {
- | ...
- | }
- </p>
- <p class='bcode w800'>
- | <jc>// Annotation on static method.</jc>
- | <jk>public class</jk> PetCreate {
- | <ja>@Example</ja>
- | <jk>public static</jk> PetCreate
<jsm>sample</jsm>() {
- | <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
- | }
- | }
- </p>
- <p class='bcode w800'>
- | <jc>// Static method with specific name 'example'.</jc>
- | <jk>public class</jk> PetCreate {
- | <jk>public static</jk> PetCreate
<jsm>example</jsm>() {
- | <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
- | }
- | }
- </p>
- <p class='bcode w800'>
- | <jc>// Static field.</jc>
- | <jk>public class</jk> PetCreate {
- | <ja>@Example</ja>
- | <jk>public static</jk> PetCreate
<jsf>EXAMPLE</jsf> = <jk>new</jk> PetCreate(<js>"Doggie"</js>, 9.99f,
<js>"Dog"</js>, <jk>new</jk> String[] {<js>"friendly"</js>,<js>"cute"</js>});
- | }
- </p>
- <p>
- Examples can also be specified via generic properties as well
using the {@del oaj.BeanContext.Builder#example(String,Object)} setting
- or {@link oaj.annotation.Bean#example @Bean(example)}
annotation at either the class or method level.
- </p>
- <p class='bcode w800'>
- | <jc>// Examples defined at class level.</jc>
- | <ja>@Rest</ja>(...)
- | <ja>@Bean</ja>(
- | onClass=PetCreate.<jk>class</jk>,
- |
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- | )
- </p>
- <p>
- Response headers are also rendered in the Swagger UI:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.4.png'>
- <p>
- These can be auto-generated from {@link
oaj.http.annotation.Header @Header} annotations defined on method
- parameters or when the parameter type is the mutable {@link
oaj.Value} object.
- The example above shows one of each:
- </p>
- <p class='bcode w800'>
- | <ja>@RestGet</ja>(
- | path=<js>"/user/login"</js>,
- | summary=<js>"Logs user into the system"</js>,
- | swagger=<ja>@OpSwagger</ja>(
- | tags=<js>"user"</js>
- | )
- | )
- | <jk>public</jk> Ok login(
- | <ja>@Query</ja>(
- | name=<js>"username"</js>,
- | description=<js>"The username
for login"</js>,
- | required=<jk>true</jk>,
- | example=<js>"myuser"</js>
- | )
- | String <jv>username</jv>,
- | <ja>@Query</ja>(
- | name=<js>"password"</js>,
- | description=<js>"The password
for login in clear text"</js>,
- | required=<jk>true</jk>,
- | example=<js>"abc123"</js>
- | )
- | String <jv>password</jv>,
- | <ja>@Header</ja>(
- | name=<js>"X-Rate-Limit"</js>,
- | type=<js>"integer"</js>,
- | format=<js>"int32"</js>,
- | description=<js>"Calls per hour
allowed by the user."</js>,
- | example=<js>"123"</js>
- | )
- | Value<Integer> <jv>rateLimit</jv>,
- | Value<ExpiresAfter>
<jv>expiresAfter</jv>,
- | RestRequest <jv>req</jv>,
- | RestResponse <jv>res</jv>
- | ) <jk>throws</jk> InvalidLogin, NotAcceptable {
- |
- | <jk>if</jk> (!
<jf>store</jf>.isValid(<jv>username</jv>, <jv>password</jv>))
- | <jk>throw new</jk> InvalidLogin();
- |
- | Date <jv>d</jv> = <jk>new</jk>
Date(System.<jsm>currentTimeMillis</jsm>() + 30 * 60 * 1000);
- |
<jv>req</jv>.getSession().setAttribute(<js>"login-expires"</js>, d);
- | <jv>rateLimit</jv>.set(1000);
- | <jv>expiresAfter</jv>.set(<jk>new</jk>
ExpiresAfter(<jv>d</jv>));
- | <jk>return</jk> <jsf>OK</jsf>;
- | }
- </p>
- <p class='bcode w800'>
- | <ja>@Header</ja>(
- | name=<js>"X-Expires-After"</js>,
- | type=<js>"string"</js>,
- | format=<js>"date-time"</js>,
- | description=<js>"Date in UTC when token
expires"</js>,
- | example=<js>"2012-10-21"</js>
- | )
- | <jk>public static class</jk> ExpiresAfter {
- | <jk>private final</jk> Calendar <jf>c</jf>;
- | <jk>public</jk> ExpiresAfter(Date <jv>d</jv>) {
- | <jk>this</jk>.<jf>c</jf> = <jk>new</jk>
GregorianCalendar();
- | <jf>c</jf>.setTime(<jv>d</jv>);
- | }
- | <jk>public</jk> Calendar toCalendar() {
- | <jk>return</jk> <jf>c</jf>;
- | }
- | }
- </p>
-</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/10.jrs.SwaggerStylesheet.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerStylesheet.html
similarity index 97%
rename from
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/10.jrs.SwaggerStylesheet.html
rename to
juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerStylesheet.html
index 275b41d..c00d44d 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/10.jrs.SwaggerStylesheet.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/15.jrs.Swagger/08.jrs.SwaggerStylesheet.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'SwaggerUI.css', flags:'todo'}
+{title:'SwaggerUI.css'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/16.jrs.ExecutionStatistics.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/16.jrs.ExecutionStatistics.html
index ac3cd03..5808043 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/16.jrs.ExecutionStatistics.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/16.jrs.ExecutionStatistics.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'REST method execution statistics', created:'8.1.3', flags:'todo'}
+{title:'REST method execution statistics', created:'8.1.3', updated:'9.0.0'}
<div class='topic'>
<p>
@@ -21,7 +21,33 @@
and <ja>@RestHook</ja> annotated methods on the class.
</p>
<p>
- The statistics are made available via the subpath <c>/stats</c>
as shown below in the <c>HelloWorldResource</c> example:
+ If you extend from {@link oajr.BasicRestServlet} or {@link
oajr.BasicRestObject}, then
+ the statics are made available through the REST interface via
the following method:
+ </p>
+ <p class='bcode w800'>
+ <ja>@RestGet</ja>(
+ path=<js>"/stats"</js>,
+ summary=<js>"Timing statistics"</js>,
+ description=<js>"Timing statistics for method invocations on
this resource."</js>
+ )
+ <ja>@HtmlDocConfig</ja>(
+ <jc>// Should override config annotations defined on class.</jc>
+ rank=10,
+ <jc>// Override the nav links for the swagger page.</jc>
+ navlinks={
+ <js>"back: servlet:/"</js>,
+ <js>"json:
servlet:/stats?Accept=text/json&plainText=true"</js>
+ },
+ <jc>// Never show aside contents of page inherited from
class.</jc>
+ aside=<js>"NONE"</js>
+ )
+ <ja>@Override</ja> <jc>/* BasicRestOperations */</jc>
+ <jk>public</jk> RestContextStats getStats(RestRequest <jv>req</jv>) {
+ <jk>return</jk> <jv>req</jv>.getContext().getStats();
+ }
+ </p>
+ <p>
+ Rendered in a browser, it looks like this:
</p>
<img class='bordered w900'
src='doc-files/jrs.ExecutionStatistics.1.png'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation.html
index 8c0d190..332b2c7 100644
--- a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation.html
+++ b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'@HtmlDocConfig', updated:'8.1.0', flags:'todo'}
+{title:'@HtmlDocConfig', updated:'8.1.0,9.0.0'}
<div class='topic'>
<p>
@@ -26,26 +26,16 @@
<li>{@link oajr.annotation.RestOp @RestOp}-annotated methods.
</ul>
<p>
- The annotation itself is just a convenience for setting
configuration properties set
- on the {@link oaj.html.HtmlDocSerializer} class.
- For example, the following two pieces of code are equivalent:
+ For example, the following shows setting the title on a page:
</p>
<p class='bcode w800'>
- | <jc>// Title defined via property.</jc>
- | <ja>@Rest</ja>(
- | properties={
- |
<ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>, value=<js>"My Resource
Page"</js>)
- | }
- | )
- |
- | <jc>// Title defined via @HtmlDoc annotation.</jc>
- | <ja>@Rest</ja>()
+ | <ja>@Rest</ja>
| <ja>@HtmlDocConfig</ja>(
| title=<js>"My Resource Page"</js>
| )
</p>
<p>
- The purpose of these annotation is to populate the HTML
document view which by default consists of the following
+ The purpose of this annotation is to populate the HTML document
view which by default consists of the following
structure:
</p>
<p class='bcode w800'>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/01.jrs.HtmlUIvsDI.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/01.jrs.HtmlUIvsDI.html
index b18ff61..2e034c1 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/01.jrs.HtmlUIvsDI.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/01.jrs.HtmlUIvsDI.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'User Interfaces (UI) vs. Developer Interfaces (DI)', flags:'todo'}
+{title:'User Interfaces (UI) vs. Developer Interfaces (DI)'}
<div class='topic'>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/02.jrs.HtmlWidgets.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/02.jrs.HtmlWidgets.html
index 762814d..b16eac2 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/02.jrs.HtmlWidgets.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/02.jrs.HtmlWidgets.html
@@ -13,19 +13,16 @@
***************************************************************************************************************************/
-->
-{title:'Widgets', flags:'todo'}
+{title:'Widgets', updated:'9.0.0'}
<div class='topic'>
<p>
The {@link oajr.widget.Widget} class allows you to add
arbitrary HTML, CSS, and Javascript
to HTML pages.
- <br>They are registered in the following locations:
+ <br>They are registered in the following location:
</p>
<ul class='javatree'>
- <li class='ja'>{@del oajr.annotation.HtmlDoc#widgets()
HtmlDoc(widgets)}
- <li class='jm'>{@del RestContext.Builder#widgets(Class...)}
- <li class='jm'>{@del RestContext.Builder#widgets(Widget...)}
- <li class='jf'>{@del RestContext#REST_widgets}
+ <li class='ja'>{@link
oaj.html.annotation.HtmlDocConfig#widgets() HtmlDocConfig(widgets)}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bcode w800'>
@@ -97,35 +94,4 @@
| }
| }
</p>
- <p>
- The <l>Widget</l> class also defines the following two
convenience methods for loading Javascript and CSS
- files from the classpath or file system.
- </p>
- <ul class='javatree'>
- <li class='jac'>{@link oajr.widget.Widget}
- <ul>
- <li class='jm'>{@del
getClasspathResourceAsString(String)}
- <li class='jm'>{@del
getClasspathResourceAsString(String,Locale)}
- </ul>
- </ul>
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- | <jk>public class</jk> MyWidget <jk>extends</jk> Widget {
- |
- | ...
- |
- | <ja>@Override</ja> <jc>/* Widget */</jc>
- | <jk>public</jk> String getScript(RestRequest
<jv>req</jv>) <jk>throws</jk> Exception {
- | <jk>return</jk>
getClasspathResourceAsString(<js>"MyWidget.js"</js>);
- | }
- |
- | <ja>@Override</ja> <jc>/* Widget */</jc>
- | <jk>public</jk> String getStyle(RestRequest
<jv>req</jv>) <jk>throws</jk> Exception {
- | <jk>return</jk>
getClasspathResourceAsString(<js>"MyWidget.css"</js>);
- | }
- | }
- </p>
- <ul class='seealso'>
- <li class='jf'>{@del oajr.RestContext#REST_widgets}
- </ul>
</div>
\ No newline at end of file
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/03.jrs.HtmlPredefinedWidgets.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/03.jrs.HtmlPredefinedWidgets.html
index 9aeeda1..01447c0 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/03.jrs.HtmlPredefinedWidgets.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/03.jrs.HtmlPredefinedWidgets.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Predefined Widgets', flags:'todo'}
+{title:'Predefined Widgets', updated:'9.0.0'}
<div class='topic'>
<p>
@@ -84,21 +84,19 @@
An example of this widget can be found in the
<c>PetStoreResource</c> in the examples that provides a drop-down menu item for
rendering all other supported content types in plain text:
</p>
<p class='bcode w800'>
- | <ja>@RestGet</ja>(
- | path=<js>"/"</js>,
+ | <ja>@RestGet</ja>(path=<js>"/"</js>)
+ | <ja>@HtmlDocConfig</ja>(
| widgets={
| ContentTypeMenuItem.<jk>class</jk>,
| },
- | htmldoc=<ja>@HtmlDoc</ja>(
- | navlinks={
- | <js>"up: ..."</js>,
- | <js>"options: ..."</js>,
- | <js>"$W{QueryMenuItem}"</js>,
- |
<js>"$W{ContentTypeMenuItem}"</js>,
- | <js>"$W{ThemeMenuItem}"</js>,
- | <js>"source: ..."</js>
- | }
- | )
+ | navlinks={
+ | <js>"up: ..."</js>,
+ | <js>"options: ..."</js>,
+ | <js>"$W{QueryMenuItem}"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"$W{ThemeMenuItem}"</js>,
+ | <js>"source: ..."</js>
+ | }
| )
| <jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -116,7 +114,7 @@
</p>
<p>
This widget is designed to be used in conjunction with the
{@link oajr.converter.Queryable} converter, although implementations
- can process the query parameters themselves if they wish to do
so by using the {@del RequestQuery#getSearchArgs()}
+ can process the query parameters themselves if they wish to do
so by using the {@link oajr.httppart.RequestQueryParams#getSearchArgs()}
method to retrieve the arguments and process the data
themselves.
</p>
<p>
@@ -125,20 +123,20 @@
<p class='bcode w800'>
| <ja>@RestGet</ja>(
| path=<js>"/"</js>,
+ | converters=Queryable.<jk>class</jk>
+ | )
+ | <ja>@HtmlDocConfig</ja>(
| widgets={
| QueryMenuItem.<jk>class</jk>,
| },
- | htmldoc=<ja>@HtmlDoc</ja>(
- | navlinks={
- | <js>"up: ..."</js>,
- | <js>"options: ..."</js>,
- | <js>"$W{QueryMenuItem}"</js>,
- |
<js>"$W{ContentTypeMenuItem}"</js>,
- | <js>"$W{ThemeMenuItem}"</js>,
- | <js>"source: ..."</js>
- | }
- | ),
- | converters=Queryable.<jk>class</jk>
+ | navlinks={
+ | <js>"up: ..."</js>,
+ | <js>"options: ..."</js>,
+ | <js>"$W{QueryMenuItem}"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"$W{ThemeMenuItem}"</js>,
+ | <js>"source: ..."</js>
+ | }
| )
| <jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -169,21 +167,19 @@
a drop-down menu item for rendering all other supported content
types in plain text:
</p>
<p class='bcode w800'>
- | <ja>@RestGet</ja>(
- | path=<js>"/"</js>,
+ | <ja>@RestGet</ja>(path=<js>"/"</js>)
+ | <ja>@HtmlDocConfig</ja>(
| widgets={
| ThemeMenuItem.<jk>class</jk>,
| },
- | htmldoc=<ja>@HtmlDoc</ja>(
- | navlinks={
- | <js>"up: ..."</js>,
- | <js>"options: ..."</js>,
- | <js>"$W{QueryMenuItem}"</js>,
- |
<js>"$W{ContentTypeMenuItem}"</js>,
- | <js>"$W{ThemeMenuItem}"</js>,
- | <js>"source: ..."</js>
- | }
- | )
+ | navlinks={
+ | <js>"up: ..."</js>,
+ | <js>"options: ..."</js>,
+ | <js>"$W{QueryMenuItem}"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"$W{ThemeMenuItem}"</js>,
+ | <js>"source: ..."</js>
+ | }
| )
| <jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -200,14 +196,13 @@
Typically it's used in the footer of the page, as shown below
in the <c>AddressBookResource</c> from the examples:
</p>
<p class='bcode w800'>
- | <ja>@Rest</ja>(
- | path=<js>"/addressBook"</js>,
+ | <ja>@Rest</ja>(path=<js>"/addressBook"</js>)
+ | <ja>@HtmlDocConfig</ja>(
| widgets={
| PoweredByJuneau.<jk>class</jk>
| },
- | htmldoc=<ja>@HtmlDoc</ja>(
- | footer=<js>"$W{PoweredByJuneau}"</js>
- | )
+ | footer=<js>"$W{PoweredByJuneau}"</js>
+ | )
</p>
<p>
It renders the following image:
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/04.jrs.HtmlUiCustomization.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/04.jrs.HtmlUiCustomization.html
index e6a462b..edd503a 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/04.jrs.HtmlUiCustomization.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/04.jrs.HtmlUiCustomization.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'UI Customization', flags:'todo'}
+{title:'UI Customization', updated:'9.0.0'}
<div class='topic'>
<p>
@@ -36,32 +36,7 @@
<p class='bcode w800'>
| <ja>@Rest</ja>(
| ...
- | <jc>// HTML-page specific settings</jc>
- | htmldoc=<ja>@HtmlDoc</ja>(
- |
- | <jc>// Default page header
contents.</jc>
- | header={
- |
<js>"<h1>$RS{title}</h1>"</js>, <jc>// Use @Rest(title)</jc>
- |
<js>"<h2>$RS{operationSummary,description}</h2>"</js>, <jc>// Use
either @RestOp(summary) or @Rest(description)</jc>
- | <js>"$C{REST/header}"</js>
<jc>// Extra header HTML defined in external config file.</jc>
- | },
- |
- | <jc>// Default stylesheet to use for
the page.
- | // Can be overridden from external
config file.
- | // Default is DevOps look-and-feel (aka
Depression look-and-feel).</jc>
- |
stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>,
- |
- | <jc>// Default contents to add to the
<head> section of the HTML page.
- | // Use it to add a favicon link to the
page.</jc>
- | head={
- | <js>"<link rel='icon'
href='$U{$C{REST/favicon}}'/>"</js>
- | },
- |
- | <jc>// No default page footer contents.
- | // Can be overridden from external
config file.</jc>
- | footer=<js>"$C{REST/footer}"</js>
- | ),
- |
+
| <jc>// Optional external configuration
file.</jc>
| config=<js>"$S{juneau.configFile}"</js>,
|
@@ -70,21 +45,41 @@
| // By default, we define static files through
the external configuration file.</jc>
| staticFiles=<js>"$C{REST/staticFiles}"</js>
| )
+ | <ja>@HtmlDocConfig</ja>(
+ |
+ | <jc>// Default page header contents.</jc>
+ | header={
+ |
<js>"<h1>$RS{title}</h1>"</js>, <jc>// Use @Rest(title)</jc>
+ |
<js>"<h2>$RS{operationSummary,description}</h2>"</js>, <jc>// Use
either @RestOp(summary) or @Rest(description)</jc>
+ | <js>"$C{REST/header}"</js> <jc>//
Extra header HTML defined in external config file.</jc>
+ | },
+ |
+ | <jc>// Default stylesheet to use for the page.
+ | // Can be overridden from external config file.
+ | // Default is DevOps look-and-feel (aka
Depression look-and-feel).</jc>
+ |
stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>,
+ |
+ | <jc>// Default contents to add to the
<head> section of the HTML page.
+ | // Use it to add a favicon link to the
page.</jc>
+ | head={
+ | <js>"<link rel='icon'
href='$U{$C{REST/favicon}}'/>"</js>
+ | },
+ |
+ | <jc>// No default page footer contents.
+ | // Can be overridden from external config
file.</jc>
+ | footer=<js>"$C{REST/footer}"</js>
+ | )
+ |
| <jk>public interface</jk> BasicRestConfig {}
</p>
<p class='bcode w800'>
- | <ja>@Rest</ja>(
- | ...
- | htmldoc=<ja>@HtmlDoc</ja>(
- | htmldoc=<ja>@HtmlDoc</ja>(
- | <jc>// Basic page navigation
links.</jc>
- | navlinks={
- | <js>"up:
request:/.."</js>,
- | <js>"options:
servlet:/?method=OPTIONS"</js>
- | }
- | )
- | ),
- | ...
+ | <ja>@Rest</ja>(...)
+ | <ja>@HtmlDocConfig</ja>(
+ | <jc>// Basic page navigation links.</jc>
+ | navlinks={
+ | <js>"up: request:/.."</js>,
+ | <js>"options:
servlet:/?method=OPTIONS"</js>
+ | }
| )
| <jk>public abstract class</jk> BasicRestServlet
<jk>extends</jk> RestServlet <jk>implements</jk> BasicRestConfig {...}
</p>
@@ -93,32 +88,30 @@
| <jk>public abstract class</jk> BasicRestServletGroup
<jk>extends</jk> BasicRestServlet {...}
</p>
<p class='bcode w800'>
- <ja>@Rest</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
- widgets={
- ContentTypeMenuItem.<jk>class</jk>,
- ThemeMenuItem.<jk>class</jk>
- },
- navlinks={
- <js>"options: ?method=OPTIONS"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{ThemeMenuItem}"</js>,
- <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
- },
- aside={
- <js>"<div style='max-width:400px'
class='text'>"</js>,
- <js>" <p>This is an example of
a 'router' page that serves as a jumping-off point to child
resources.</p>"</js>,
- <js>" <p>Resources can be
nested arbitrarily deep through router pages.</p>"</js>,
- <js>" <p>Note the <span
class='link'>options</span> link provided that lets you see the
generated swagger doc for this page.</p>"</js>,
- <js>" <p>Also note the <span
class='link'>sources</span> link on these pages to view the source
code for the page.</p>"</js>,
- <js>" <p>All content on pages
in the UI are serialized POJOs. In this case, it's a serialized array of beans
with 2 properties, 'name' and 'description'.</p>"</js>,
- <js>" <p>Other features (such
as this aside) are added through annotations.</p>"</js>,
- <js>"</div>"</js>
- }
- ),
- ...
- )
- <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletGroup {...}
+ | <ja>@Rest</ja>(...)
+ | <ja>@HtmlDocConfig</ja>(
+ | widgets={
+ | ContentTypeMenuItem.<jk>class</jk>,
+ | ThemeMenuItem.<jk>class</jk>
+ | },
+ | navlinks={
+ | <js>"options: ?method=OPTIONS"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"$W{ThemeMenuItem}"</js>,
+ | <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
+ | },
+ | aside={
+ | <js>"<div style='max-width:400px'
class='text'>"</js>,
+ | <js>" <p>This is an example of
a 'router' page that serves as a jumping-off point to child
resources.</p>"</js>,
+ | <js>" <p>Resources can be
nested arbitrarily deep through router pages.</p>"</js>,
+ | <js>" <p>Note the <span
class='link'>options</span> link provided that lets you see the
generated swagger doc for this page.</p>"</js>,
+ | <js>" <p>Also note the <span
class='link'>sources</span> link on these pages to view the source
code for the page.</p>"</js>,
+ | <js>" <p>All content on pages
in the UI are serialized POJOs. In this case, it's a serialized array of beans
with 2 properties, 'name' and 'description'.</p>"</js>,
+ | <js>" <p>Other features (such
as this aside) are added through annotations.</p>"</js>,
+ | <js>"</div>"</js>
+ | }
+ | )
+ | <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletGroup {...}
</p>
<p>
diff --git
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/05.jrs.HtmlStylesheets.html
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/05.jrs.HtmlStylesheets.html
index 1a2c228..8e539b3 100644
---
a/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/05.jrs.HtmlStylesheets.html
+++
b/juneau-doc/docs/Topics/06.juneau-rest-server/17.jrs.HtmlDocAnnotation/05.jrs.HtmlStylesheets.html
@@ -13,7 +13,7 @@
***************************************************************************************************************************/
-->
-{title:'Stylesheets', updated:'8.1.0', flags:'todo'}
+{title:'Stylesheets', updated:'8.1.0,9.0.0'}
<div class='topic'>
<p>
@@ -46,12 +46,11 @@
The {@link oajr.BasicRestServlet} class defines the stylesheet
served up as a static file:
<p class='bcode w800'>
| <ja>@Rest</ja>(
- | htmldoc=<ja>@HtmlDoc</ja>(
- |
stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>,
- | ),
- |
| staticFiles={<js>"styles:styles"</js>}
| )
+ | <ja>@HtmlDocConfig</ja>(
+ |
stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>
+ | )
| <jk>public abstract class</jk> BasicRestServlet
<jk>extends</jk> RestServlet {...}
</p>
<p>
@@ -65,11 +64,11 @@
</p>
<p class='bcode w800'>
| <ja>@Rest</ja>(
- | htmldoc=<ja>@HtmlDoc</ja>(
- |
stylesheet=<js>"servlet:/my-styles/my-style.css}"</js>,
- | ),
| staticFiles={<js>"my-styles:my-styles"</js>}
| )
+ | <ja>@HtmlDocConfig</ja>(
+ |
stylesheet=<js>"servlet:/my-styles/my-style.css}"</js>
+ | )
| <jk>public class</jk> MyResourceBaseClass
<jk>extends</jk> BasicRestServlet {...}
</p>
<p>
@@ -81,19 +80,19 @@
In case you're curious about how the menu item works, it's
defined via a widget:
</p>
<p class='bcode w800'>
- | <ja>@Rest</ja>(
- | htmldoc=<ja>@HtmlDoc</ja>(
- | widgets={
- | PoweredByApache.<jk>class</jk>,
- |
ContentTypeMenuItem.<jk>class</jk>,
- | StyleMenuItem.<jk>class</jk>
- | },
- | navlinks={
- | <js>"options:
?method=OPTIONS"</js>,
- |
<js>"$W{ContentTypeMenuItem}"</js>,
- | <js>"$W{StyleMenuItem}"</js>,
- | <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
- | },
+ | <ja>@Rest</ja>(...)
+ | <ja>@HtmlDocConfig</ja>(
+ | widgets={
+ | PoweredByApache.<jk>class</jk>,
+ | ContentTypeMenuItem.<jk>class</jk>,
+ | StyleMenuItem.<jk>class</jk>
+ | },
+ | navlinks={
+ | <js>"options: ?method=OPTIONS"</js>,
+ | <js>"$W{ContentTypeMenuItem}"</js>,
+ | <js>"$W{StyleMenuItem}"</js>,
+ | <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
+ | }
| )
| <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletJenaGroup {...}
</p>
diff --git a/juneau-doc/src/main/javadoc/overview.html
b/juneau-doc/src/main/javadoc/overview.html
index 1d216d3..7dbbe0a 100644
--- a/juneau-doc/src/main/javadoc/overview.html
+++ b/juneau-doc/src/main/javadoc/overview.html
@@ -380,27 +380,25 @@
<li><p><a class='doclink'
href='#juneau-rest-server.jrs.SvlVariables'>SVL Variables</a><span
class='update'>updated: <b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='#juneau-rest-server.jrs.StaticFiles'>Static files</a><span
class='update'>updated: <b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='#juneau-rest-server.jrs.ClientVersioning'>Client Versioning</a><span
class='update'>updated: <b>9.0.0</b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger'>Swagger</a><span
class='update'><b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger'>Swagger</a></p>
<ol>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>BasicRestServlet</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>Basic Swagger
Info</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>Tags</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>Operations</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>Parameters</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples'>Parameter
Examples</a><span class='update'>updated: 8.1.0,
<b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>Responses</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples'>Response
Examples</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>Models</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>SwaggerUI.css</a><span
class='update'><b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>BasicRestServlet/BasicRestObject</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>Basic Swagger
Info</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>Tags</a></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>Operations</a></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>Parameters</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>Responses</a></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>Models</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>SwaggerUI.css</a></p>
</ol>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.ExecutionStatistics'>REST method execution
statistics</a><span class='update'>created: 8.1.3,
<b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation'>@HtmlDocConfig</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.ExecutionStatistics'>REST method execution
statistics</a><span class='update'>created: 8.1.3, updated:
<b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation'>@HtmlDocConfig</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
<ol>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>User Interfaces
(UI) vs. Developer Interfaces (DI)</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>Widgets</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>Predefined
Widgets</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>UI
Customization</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>Stylesheets</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>User Interfaces
(UI) vs. Developer Interfaces (DI)</a></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>Widgets</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>Predefined
Widgets</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>UI
Customization</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>Stylesheets</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink'
href='#juneau-rest-server.jrs.DefaultHeaders'>Default Headers</a><span
class='update'><b><red>todo</red></b></span></p>
<li><p><a class='doclink'
href='#juneau-rest-server.jrs.LoggingAndDebugging'>Logging / Debugging</a><span
class='update'>created: 8.1.0, updated: 8.2.0, <b><red>todo</red></b></span></p>
@@ -17881,7 +17879,7 @@
<!--
====================================================================================================
-->
-<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger' id='juneau-rest-server.jrs.Swagger'>6.15
- Swagger</a><span class='update'><b><red>todo</red></b></span></h3>
+<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger' id='juneau-rest-server.jrs.Swagger'>6.15
- Swagger</a></h3>
<div class='topic'><!-- START: 6.15 - juneau-rest-server.jrs.Swagger -->
<div class='topic'>
<p>
@@ -17900,12 +17898,42 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'
id='juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>6.15.1 -
BasicRestServlet</a><span class='update'>updated: 8.1.0,
<b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'
id='juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>6.15.1 -
BasicRestServlet/BasicRestObject</a><span class='update'>updated:
8.1.0,<b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.15.1 -
juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger -->
<div class='topic'>
<p>
- Any subclass of {@link org.apache.juneau.rest.BasicRestServlet}
gets an auto-generated Swagger UI when performing an <c>OPTIONS</c>
- request with <c>Accept:text/html</c>.
+ Any subclass of {@link org.apache.juneau.rest.BasicRestServlet}
and {@link org.apache.juneau.rest.BasicRestObject} gets an auto-generated
Swagger UI when performing an <c>OPTIONS</c>
+ request with <c>Accept:text/html</c> due to the following
method:
+ </p>
+ <p class='bcode w800'>
+ <ja>@RestGet</ja>(
+ path=<js>"/api/*"</js>,
+ summary=<js>"Swagger documentation"</js>,
+ description=<js>"Swagger documentation for this resource."</js>
+ )
+ <ja>@HtmlDocConfig</ja>(
+ <jc>// Should override config annotations defined on class.</jc>
+ rank=10,
+ <jc>// Override the nav links for the swagger page.</jc>
+ navlinks={
+ <js>"back: servlet:/"</js>,
+ <js>"json:
servlet:/?Accept=text/json&plainText=true"</js>
+ },
+ <jc>// Never show aside contents of page inherited from
class.</jc>
+ aside=<js>"NONE"</js>
+ )
+ <ja>@BeanConfig</ja>(
+ <jc>// POJO swaps to apply to all serializers/parsers on this
method.</jc>
+ swaps={
+ <jc>// Use the SwaggerUI swap when rendering Swagger
beans.
+ // This is a per-media-type swap that only applies to
text/html requests.</jc>
+ SwaggerUI.class
+ }
+ )
+ <ja>@Override</ja> <jc>/* BasicRestOperations */</jc>
+ <jk>public</jk> Swagger getSwagger(RestRequest <jv>req</jv>) {
+ <jk>return</jk>
<jv>req</jv>.getSwagger().orElseThrow(NotFound::<jk>new</jk>);
+ }
</p>
<p>
The underlying mechanics are simple.
@@ -17914,67 +17942,7 @@
Then that bean is swapped for a {@link
org.apache.juneau.dto.swagger.ui.SwaggerUI} bean when rendered as HTML.
</p>
<p>
- Here's the class that defines the behavior:
- </p>
- <p class='bcode w800'>
- <ja>@Rest</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>@RestOp</ja>(method=<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>
- )
- )
- <ja>@JsonSchemaConfig</ja>(
- <jc>// Add descriptions to the following types when not
specified:</jc>
-
addDescriptionsTo=<js>"bean,collection,array,map,enum"</js>,
- <jc>// Add x-example to the following types:</jc>
- addExamplesTo=<js>"bean,collection,array,map"</js>,
- <jc>// Don't generate schema information on the Swagger
bean itself or HTML beans.</jc>
-
ignoreTypes=<js>"Swagger,org.apache.juneau.dto.html5.*"</js>,
- <jc>// Use $ref references for bean definitions to
reduce duplication in Swagger.</jc>
- useBeanDefs=<js>"true"</js>
- )
- <ja>@BeanConfig</ja>(
- <jc>// When parsing generated beans, ignore unknown
properties that may only exist as getters and not setters.</jc>
- ignoreUnknownBeanProperties=<js>"true"</js>,
- <jc>// POJO swaps to apply to all serializers/parsers
on this method.</jc>
- swaps={
- <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>
- }
- )
- <jk>public</jk> Swagger getOptions(RestRequest <jv>req</jv>) {
- <jc>// Localized Swagger for this resource is available
through the RestRequest object.</jc>
- <jk>return</jk> <jv>req</jv>.getSwagger();
- }
- }
- </p>
- <p>
- Note that to have your resource create Swagger UI, you must
either extend from {@link org.apache.juneau.rest.BasicRestServlet} or provide
+ Note that to have your resource create Swagger UI, you must
either extend from one of the basic resource classes or provide
your own <ja>@RestOp</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>
@@ -17982,7 +17950,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'
id='juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>6.15.2 - Basic Swagger
Info</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'
id='juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>6.15.2 - Basic Swagger
Info</a><span class='update'>updated: <b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.15.2 -
juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo -->
<div class='topic'>
<p>
@@ -18051,7 +18019,7 @@
...
swagger=<ja>@Swagger</ja>(
<jc>// Raw Simplified JSON.</jc>
- <jc>// Values are concatenated.
+ <jc>// Values are concatenated.</jc>
<js>"{"</js>,
<js>"swagger: '2.0',"</js>,
<js>"version: '1.0.0',"</js>,
@@ -18150,7 +18118,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>6.15.3 - Tags</a><span
class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>6.15.3 - Tags</a></h4>
<div class='topic'><!-- START: 6.15.3 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerTags -->
<div class='topic'>
<p>
@@ -18252,7 +18220,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>6.15.4 -
Operations</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>6.15.4 -
Operations</a></h4>
<div class='topic'><!-- START: 6.15.4 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations -->
<div class='topic'>
<p>
@@ -18297,7 +18265,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>6.15.5 -
Parameters</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>6.15.5 -
Parameters</a><span class='update'>updated: <b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.15.5 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters -->
<div class='topic'>
<p>
@@ -18313,27 +18281,29 @@
<jk>public</jk> Collection<Pet> getPets(
<ja>@Query</ja>(
name=<js>"s"</js>,
- description={
- <js>"Search."</js>,
- <js>"Key/value pairs representing
column names and search tokens."</js>,
- <js>"'*' and '?' can be used as
meta-characters in string fields."</js>,
- <js>"'>', '>=', '<', and
'<=' can be used as limits on numeric and date fields."</js>,
- <js>"Date fields can be matched with
partial dates (e.g. '2018' to match any date in the year 2018)."</js>
- },
- type=<js>"array"</js>,
- collectionFormat=<js>"csv"</js>,
- example=<js>"Bill*,birthDate>2000"</js>
+ schema=<ja>@Schema</ja>(
+ description={
+ <js>"Search."</js>,
+ <js>"Key/value pairs
representing column names and search tokens."</js>,
+ <js>"'*' and '?' can be used as
meta-characters in string fields."</js>,
+ <js>"'>', '>=', '<',
and '<=' can be used as limits on numeric and date fields."</js>,
+ <js>"Date fields can be matched
with partial dates (e.g. '2018' to match any date in the year 2018)."</js>
+ },
+ type=<js>"array"</js>,
+ collectionFormat=<js>"csv"</js>
+ )
)
String[] <jv>s</jv>,
<ja>@Query</ja>(
name=<js>"v"</js>,
- description={
- <js>"View."</js>,
- <js>"Column names to display."</js>
- },
- type=<js>"array"</js>,
- collectionFormat=<js>"csv"</js>,
- example=<js>"name,birthDate"</js>
+ schema=<ja>@Schema</ja>(
+ description={
+ <js>"View."</js>,
+ <js>"Column names to
display."</js>
+ },
+ type=<js>"array"</js>,
+ collectionFormat=<js>"csv"</js>
+ )
)
String[] <jv>v</jv>,
...
@@ -18341,11 +18311,13 @@
...
}
</p>
- <p>
- <b>Note:</b> The <c>type</c> and <c>collectionFormat</c>
values above are optional and auto-detected based on the
- parameter class type if omitted. They're included here for
clarity.
- The examples will be explained in the next section.
- </p>
+ <ul class='spaced-list'>
+ <li class='note'>The {@link
org.apache.juneau.http.annotation.Schema @Schema} annotation can also be
attached
+ directly to the parameter or parameter type as well.
+ <li class='note'>The {@link
org.apache.juneau.http.annotation.Schema#type() type} and {@link
org.apache.juneau.http.annotation.Schema#collectionFormat() collectionFormat}
values above are optional and auto-detected based on the
+ parameter class type if omitted. They're included here
for clarity.
+ The examples will be explained in the next section.
+ </ul>
<p>
Another option is to specify your parameter information in the
<c>parameters</c> annotation as free-form Simple JSON.
In the case of the <c>PetStoreResource.getPets()</c> method, we
pull this information from a static field
@@ -18421,7 +18393,9 @@
)
)
<jk>public</jk> Ok postPet(
- <ja>@Body</ja>(description=<js>"Pet object to add to
the store"</js>) PetCreate <jv>pet</jv>
+ <ja>@Body</ja>
+ <ja>@Schema</ja>(description=<js>"Pet object to add to
the store"</js>)
+ PetCreate <jv>pet</jv>
) <jk>throws</jk> IdConflict, NotAcceptable,
UnsupportedMediaType {
<jf>store</jf>.create(<jv>pet</jv>);
@@ -18436,235 +18410,8 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples'>6.15.6 -
Parameter Examples</a><span class='update'>updated: 8.1.0,
<b><red>todo</red></b></span></h4>
-<div class='topic'><!-- START: 6.15.6 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples -->
-<div class='topic'>
- <p>
- The <c>model</c> select box in the parameters can be expanded
to show examples:
- </p>
- <img class='bordered w900' src='doc-files/jrs.Swagger.Parameters.1.png'>
- <p>
- The examples for query/form-data/path/header parameters can be
defined using the <c>example</c> attribute on your annotated parameters as
shown here:
- </p>
- <p class='bcode w800'>
- <ja>@RestGet</ja>
- <jk>public</jk> Collection<Pet> getPets(
- <ja>@Query</ja>(
- name=<js>"s"</js>,
- description={
- <js>"Search."</js>,
- <js>"Key/value pairs representing
column names and search tokens."</js>,
- <js>"'*' and '?' can be used as
meta-characters in string fields."</js>,
- <js>"'>', '>=', '<', and
'<=' can be used as limits on numeric and date fields."</js>,
- <js>"Date fields can be matched with
partial dates (e.g. '2018' to match any date in the year 2018)."</js>
- },
- type=<js>"array"</js>,
- collectionFormat=<js>"csv"</js>,
- example=<js>"Bill*,birthDate>2000"</js>
- )
- String[] <jv>query</jv>,
- ...
- ) <jk>throws</jk> NotAcceptable {
- ...
- }
- </p>
- <p>
- This value gets converted to an <c>x-examples</c> attribute in
your parameter information:
- </p>
- <p class='bcode w800'>
- {
- <jok>"swagger"</jok>: <jov>"2.0"</jov>,
- <jok>"paths"</jok>: {
- <jok>"/pet"</jok>: {
- <jok>"get"</jok>: {
- <jok>"operationId"</jok>:
<jov>"getPets"</jov>,
- <jok>"summary"</jok>: <jov>"All pets in
the store"</jov>,
- <jok>"parameters"</jok>: [
- {
- <jok>"in"</jok>:
<jov>"query"</jov>,
- <jok>"name"</jok>:
<jov>"s"</jov>,
- ...
-
<jok>"x-examples"</jok>: {
-
<jok>"example"</jok>: <jov>"?s=Bill*,birthDate>2000"</jov>
- }
- },
- ...
- </p>
- <p>
- Examples for request bodies includes all supported
<c>Content-Type</c> values:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.Parameters.3.png'>
- <p>
- These are based on the parsers registered on your servlet or
method.
- </p>
- <p>
- Selecting any of the content types shows you a representative
example for the POJO:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.Parameters.4.png'>
- <p>
- There are several options for defining examples for request
bodies:
- </p>
- <ul class='spaced-list'>
- <li>
- {@del org.apache.juneau.http.annotation.Body#example()
@Body(example)} annotation.
- <li>
- {@del org.apache.juneau.http.annotation.Body#examples()
@Body(examples)} annotation.
- <li>
- Defining an <js>"x-examples"</js> field in the
inherited Swagger JSON body field (classpath file or
<c><ja>@Swagger</ja>(value)</c>/<c><ja>@OpSwagger</ja>(value)</c>).
- <li>
- Defining an <js>"x-examples"</js> field in the Swagger
Schema Object for the body (including referenced <js>"$ref"</js> schemas).
- <li>
- Allowing Juneau to auto-generate a code example.
- </ul>
- <p>
- When using {@del
org.apache.juneau.http.annotation.Body#example() @Body(example)}, you specify a
Simple JSON representation of your POJO.
- The Swagger generator will then convert that JSON into a POJO
using the registered serializers on the REST method to produce examples for all
- supported language types.
- </p>
-
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jc>// A JSON representation of a PetCreate object.</jc>
- <ja>@Body</ja>(
-
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- )
- </p>
-
- <p>
- The {@del org.apache.juneau.http.annotation.Body#examples()
@Body(examples)} annotation allows you to specify raw output values per media
type.
- This field allows you to override the behavior and show
examples for only specified media types or different examples for different
media types.
- </p>
-
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jc>// A JSON representation of a PetCreate object.</jc>
- <ja>@Body</ja>(
- examples={
-
<js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
- <js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
- }
- )
- </p>
- <p>
- The Swagger generator uses these to create an <c>x-examples</c>
entry in your generated Swagger:
- </p>
- <p class='bcode w800'>
- <jok>"/pet"</jok>: {
- <jok>"post"</jok>: {
- <jok>"operationId"</jok>: <jov>"postPet"</jov>,
- <jok>"summary"</jok>: <jov>"Add a new pet to the
store"</jov>,
- <jok>"parameters"</jok>: [
- {
- <jok>"in"</jok>: <jov>"body"</jov>,
- <jok>"description"</jok>: <jov>"Pet
object to add to the store"</jov>,
- <jok>"required"</jok>: <jov>true</jov>,
- <jok>"schema"</jok>: {
- <jok>"$ref"</jok>:
<jov>"#/definitions/PetCreate"</jov>
- },
- <jok>"x-examples"</jok>: {
- <jok>"application/json"</jok>:
<jov>"{\n\t\"name\": \"Doggie\",\n\t\"species\": \"Dog\",\n\t\"price\":
9.99,\n\t\"tags\": [\n..."</jov>,
-
<jok>"application/json+simple"</jok>: <jov>"{\n\tname: 'Doggie',\n\tspecies:
'Dog',\n\tprice: 9.99,\n\ttags: [\n\t\t'friendly..."</jov>,
- <jok>"text/xml"</jok>:
<jov>"<?xml version=\"1.0\"
encoding=\"UTF-8\"?>\n<object>\n\t<name>Doggie</name&..."</jov>,
-
<jok>"text/html+stripped"</jok>:
<jov>"<table>\n\t<tr>\n\t\t<td>name</td>\n\t\t<td>Doggie</t..."</jov>,
- <jok>"text/uon"</jok>:
<jov>"(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)"</jov>,
-
<jok>"application/x-www-form-urlencoded"</jok>:
<jov>"name=Doggie\n&species=Dog\n&price=9.99\n&tags=@(\n\tfriendly,\n\tcute\n)"</jov>,
- <jok>"text/openapi"</jok>:
<jov>"(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)"</jov>,
- <jok>"octal/msgpack"</jok>:
<jov>"84 A4 6E 61 6D 65 A6 44 6F 67 67 69 65 A7 73 70 65 63 69 65 73 A3 44 6F
67 A5 70 72 69 63 6..."</jov>,
- <jok>"text/plain"</jok>:
<jov>"{name:'Doggie',species:'Dog',price:9.99,tags:['friendly','cute']}"</jov>,
- <jok>"text/xml+rdf"</jok>:
<jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"ht..."</jov>,
- <jok>"text/turtle"</jok>:
<jov>"@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.a...";</jov>,
- <jok>"text/n-triple"</jok>:
<jov>"_:A59722791X3aX165d321a2b4X3aXX2dX7fca
<http://www.apache.org/juneaubp/name> \"Doggie..."</jov>,
- <jok>"text/n3"</jok>:
<jov>"@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apach...";</jov>
- }
- }
- ],
- </p>
- <p>
- Another option is to define these directly in your resource
Swagger JSON file, or via {@link
org.apache.juneau.rest.annotation.Rest#swagger() @Rest(swagger)}/{@link
org.apache.juneau.rest.annotation.RestOp#swagger() @RestOp(swagger)}.
- </p>
- <p>
- Juneau also supports auto-generation of JSON-Schema directly
from POJO classes.
- By default, the generated swagger uses to the {@del
org.apache.juneau.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- setting to automatically add examples to beans, collections,
arrays, and maps:
- </p>
- <p class='bcode w800'>
- <jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {
-
- <ja>@RestOp</ja>(method=<jsf>OPTIONS</jsf>, path=<js>"/*"</js>,
- ...
- )
- <ja>@JsonSchemaConfig</ja>(
- <jc>// Add x-example to the following types:</jc>
- addExamplesTo=<js>"bean,collection,array,map"</js>,
- ...
- )
- <jk>public</jk> Swagger getOptions(RestRequest req) {...}
- </p>
- <p>
- Examples can be defined via static methods, fields, and
annotations on the classes themselves.
- </p>
- <h5 class='figure'>Examples:</h5>
- <p class='bcode w800'>
- <jc>// Annotation on class.</jc>
-
<ja>@Example</ja>(<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>)
- <jk>public class</jk> PetCreate {
- ...
- }
- </p>
- <p class='bcode w800'>
- <jc>// Annotation on static method.</jc>
- <jk>public class</jk> PetCreate {
- <ja>@Example</ja>
- <jk>public static</jk> PetCreate <jsm>sample</jsm>() {
- <jk>return new</jk>
PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk> String[]
{<js>"friendly"</js>,<js>"cute"</js>});
- }
- }
- </p>
- <p class='bcode w800'>
- <jc>// Static method with specific name 'example'.</jc>
- <jk>public class</jk> PetCreate {
- <jk>public static</jk> PetCreate <jsm>example</jsm>() {
- <jk>return new</jk> PetCreate(<js>"Doggie"</js>, 9.99f,
<js>"Dog"</js>, <jk>new</jk> String[] {<js>"friendly"</js>,<js>"cute"</js>});
- }
- }
- </p>
- <p class='bcode w800'>
- <jc>// Static field.</jc>
- <jk>public class</jk> PetCreate {
- <ja>@Example</ja>
- <jk>public static</jk> PetCreate <jsf>EXAMPLE</jsf> =
<jk>new</jk> PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk>
String[] {<js>"friendly"</js>,<js>"cute"</js>});
- }
- </p>
- <p>
- Examples can also be specified via generic properties as well
using the {@link org.apache.juneau.BeanContext.Builder#example(Class,Object)}
setting or {@del org.apache.juneau.annotation.BeanConfig#examples()
@BeanConfig(examples)} annotation at either the class or method level.
- </p>
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jc>// Examples defined at class level.</jc>
- <ja>@Rest</ja>(...)
- <ja>@BeanConfig</ja>(
- examples=<js>"{PetCreate:
{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}"</js>
- )
- </p>
- <ul class='seealso'>
- <li class='ja'>{@link org.apache.juneau.annotation.Example}
- <li class='jc'>{@link org.apache.juneau.BeanContext.Builder}
- <ul>
- <li class='jf'>{@link
org.apache.juneau.BeanContext.Builder#example(Class,Object)
example(Class,Object)}
- </ul>
- <li class='jc'>{@link
org.apache.juneau.jsonschema.JsonSchemaGenerator}
- <ul>
- <li class='jf'>{@del
org.apache.juneau.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- <li class='jf'>{@del
org.apache.juneau.jsonschema.JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples
JSONSCHEMA_allowNestedExamples}
- </ul>
- </ul>
-</div>
-</div><!-- END: 6.15.6 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples -->
-
-<!--
====================================================================================================
-->
-
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>6.15.7 -
Responses</a><span class='update'><b><red>todo</red></b></span></h4>
-<div class='topic'><!-- START: 6.15.7 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses -->
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>6.15.6 -
Responses</a></h4>
+<div class='topic'><!-- START: 6.15.6 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses -->
<div class='topic'>
<p>
Under the input parameters are listed the possible responses
for the resource:
@@ -18703,256 +18450,25 @@
<li class='link'>{@doc jrs.ResponseBeans}
</ul>
</div>
-</div><!-- END: 6.15.7 - juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses
-->
-
-<!--
====================================================================================================
-->
-
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples'>6.15.8 -
Response Examples</a><span class='update'><b><red>todo</red></b></span></h4>
-<div class='topic'><!-- START: 6.15.8 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples -->
-<div class='topic'>
- <p>
- The <c>model</c> select box in the responses can be expanded to
show examples:
- </p>
- <h5 class='figure'>PetStoreResource.getPet()</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.1.png'>
- <p>
- Examples are provided for any supported <c>Accept</c> type
based on the serializers defined on your
- servlet/method.
- </p>
- <h5 class='figure'>application/json+simple</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.2.png'>
- <h5 class='figure'>text/uon</h5>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.3.png'>
- <p>
- Examples are pulled from the <c>examples</c> attribute in the
response object of the generated Swagger JSON:
- </p>
- <p class='bcode w800'>
- <jok>"/pet/{petId}"</jok>: {
- <jok>"get"</jok>: {
- <jok>"operationId"</jok>: <jov>"getPet"</jov>,
- <jok>"summary"</jok>: <jov>"Find pet by ID"</jov>,
- <jok>"description"</jok>: <jov>"Returns a single
pet"</jov>,
- <jok>"responses"</jok>: {
- <jok>"200"</jok>: {
- <jok>"description"</jok>:
<jov>"OK"</jov>,
- <jok>"schema"</jok>: {
- <jok>"$ref"</jok>:
<jov>"#/definitions/Pet"</jov>
- },
- <jok>"examples"</jok>: {
-
<jok>"text/html+stripped"</jok>:
<jov>"<table>\n\t<tr>\n\t\t<td>id</td>\n\t\t<td>\t\t\t<a
href=\"..."</jov>,
- <jok>"text/html+schema"</jok>:
<jov>"<html>\n\t<head>\n\t\t<link rel='icon'
href='$U{servlet:/htdocs/cat.png}'/>..."</jov>,
- <jok>"application/json"</jok>:
<jov>"{\n\t\"id\": 123,\n\t\"species\": {\n\t\t\"name\": \"Dog\",\n\t\t\"id\":
123\n\t},\n\t\"name\..."</jov>,
-
<jok>"application/json+simple"</jok>: <jov>"{\n\tid: 123,\n\tspecies:
{\n\t\tname: 'Dog',\n\t\tid: 123\n\t},\n\tname: 'Doggie',\n\..."</jov>,
-
<jok>"application/json+schema"</jok>: <jov>"{\n\t\"type\":
\"object\",\n\t\"properties\": {\n\t\t\"id\": {\n\t\t\t\"type\":
\"inte..."</jov>,
- <jok>"text/xml"</jok>:
<jov>"<?xml version=\"1.0\"
encoding=\"UTF-8\"?>\n<Pet>\n\t<id>123</id>\n\t<spec..."</jov>,
- <jok>"text/xml+schema"</jok>:
<jov>"<schema xmlns=\"http://www.w3.org/2001/XMLSchema\";
targetNamespace=\"http://www.apache.org/...";</jov>,
- <jok>"text/uon"</jok>:
<jov>"(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\t\tn..."</jov>,
-
<jok>"application/x-www-form-urlencoded"</jok>:
<jov>"id=123\n&species=(\n\tname=Dog,\n\tid=123\n)\n&name=Doggie\n&tags=@(\n\t(\n\..."</jov>,
- <jok>"text/openapi"</jok>:
<jov>"(\n\tid=123,\n\tspecies=(\n\t\tname=Dog,\n\t\tid=123\n\t),\n\tname=Doggie,\n\ttags=@(\n\t\t(\n\t\..."</jov>,
- <jok>"octal/msgpack"</jok>:
<jov>"86 A2 69 64 7B A7 73 70 65 63 69 65 73 82 A4 6E 61 6D 65 A3 44 6F 67 A2
69 64 7B A4 6E 61 6D 65 ..."</jov>,
- <jok>"text/xml+soap"</jok>:
<jov>"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Envelope
soap=\"http://www.w3.org/2003/05/...";</jov>,
- <jok>"text/plain"</jok>:
<jov>"{id:123,species:{name:'Dog',id:123},name:'Doggie',tags:[{name:'MyTag',id:123}],price:0.0,status:'AV..."</jov>,
- <jok>"text/xml+rdf"</jok>:
<jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"http://...";</jov>,
-
<jok>"text/xml+rdf+abbrev"</jok>: <jov>"<rdf:RDF\n
xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n
xmlns:j=\"..."</jov>,
- <jok>"text/turtle"</jok>:
<jov>"@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apache...";</jov>,
- <jok>"text/n-triple"</jok>:
<jov>"_:A720f0f4fX3aX165d4974933X3aXX2dX7f93
<http://www.apache.org/juneaubp/name> \"Dog\" .\n_:..."</jov>,
- <jok>"text/n3"</jok>:
<jov>"@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j:
<http://www.apache.org...";</jov>
- </p>
- <p>
- There are several options for defining examples for response
bodies:
- </p>
- <ul class='spaced-list'>
- <li>
- {@del
org.apache.juneau.http.annotation.Response#example() @Response(example)}
annotation.
- <li>
- {@link
org.apache.juneau.http.annotation.Response#examples() @Response(examples)}
annotation.
- <li>
- Defining an <js>"examples"</js> field in the inherited
Swagger JSON response object (classpath file or
<c><ja>@Swagger</ja>(value)</c>/<c><ja>@OpSwagger</ja>(value)</c>).
- <li>
- Defining an <js>"examples"</js> field in the Swagger
Schema Object for the response object (including referenced <js>"$ref"</js>
schemas).
- <li>
- Allowing Juneau to auto-generate a code example.
- </ul>
-
- <p>
- The {@del org.apache.juneau.http.annotation.Response#example
@Response(example)} annotation can be used on either your
<ja>@RestOp</ja>-annotated
- method or return class to define the example of the body.
- </p>
- <p class='bcode w800'>
- <jc>// A JSON representation of a Pet object.</jc>
- <ja>@Response</ja>(
-
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- )
- </p>
- <p>
- This is a Simple JSON representation of the body that is
converted to a POJO and then serialized to all the registered serializers on
the REST method to produce examples for all
- supported language types.
- These values are then used to automatically populate the
<c>examples</c> field.
- </p>
- <p>
- Direct per-media-type examples can also be defined using the
{@link org.apache.juneau.http.annotation.Response#examples @Response(examples)}
annotation:
- </p>
- <p class='bcode w800'>
- <jc>// A JSON representation of a PetCreate object.</jc>
- <ja>@Response</ja>(
- examples={
-
<js>"'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',"</js>,
- <js>"'text/uon':'(name:Doggie,species=Dog)'"</js>
- }
- )
- </p>
-
- <p>
- Juneau also supports auto-generation of JSON-Schema directly
from POJO classes.
- By default, the generated swagger uses to the {@del
org.apache.juneau.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo
JSONSCHEMA_addExamplesTo}
- setting to automatically add examples to beans, collections,
arrays, and maps:
- </p>
- <p>
- In particular, examples can be defined via static methods,
fields, and annotations on the classes themselves.
- </p>
- <p class='bcode w800'>
- <jc>// Annotation on class.</jc>
-
<ja>@Example</ja>(<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>)
- <jk>public class</jk> PetCreate {
- ...
- }
- </p>
- <p class='bcode w800'>
- <jc>// Annotation on static method.</jc>
- <jk>public class</jk> PetCreate {
- <ja>@Example</ja>
- <jk>public static</jk> PetCreate <jsm>sample</jsm>() {
- <jk>return new</jk> PetCreate(<js>"Doggie"</js>, 9.99f,
<js>"Dog"</js>, <jk>new</jk> String[] {<js>"friendly"</js>,<js>"cute"</js>});
- }
- }
- </p>
- <p class='bcode w800'>
- <jc>// Static method with specific name 'example'.</jc>
- <jk>public class</jk> PetCreate {
- <jk>public static</jk> PetCreate <jsm>example</jsm>() {
- <jk>return new</jk> PetCreate(<js>"Doggie"</js>, 9.99f,
<js>"Dog"</js>, <jk>new</jk> String[] {<js>"friendly"</js>,<js>"cute"</js>});
- }
- }
- </p>
- <p class='bcode w800'>
- <jc>// Static field.</jc>
- <jk>public class</jk> PetCreate {
- <ja>@Example</ja>
- <jk>public static</jk> PetCreate <jsf>EXAMPLE</jsf> =
<jk>new</jk> PetCreate(<js>"Doggie"</js>, 9.99f, <js>"Dog"</js>, <jk>new</jk>
String[] {<js>"friendly"</js>,<js>"cute"</js>});
- }
- </p>
- <p>
- Examples can also be specified via generic properties as well
using the {@del org.apache.juneau.BeanContext.Builder#example(String,Object)}
setting
- or {@link org.apache.juneau.annotation.Bean#example
@Bean(example)} annotation at either the class or method level.
- </p>
- <p class='bcode w800'>
- <jc>// Examples defined at class level.</jc>
- <ja>@Rest</ja>(...)
- <ja>@Bean</ja>(
- onClass=PetCreate.<jk>class</jk>,
-
example=<js>"{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}"</js>
- )
- </p>
- <p>
- Response headers are also rendered in the Swagger UI:
- </p>
- <img class='bordered w900'
src='doc-files/jrs.Swagger.ResponseExamples.4.png'>
- <p>
- These can be auto-generated from {@link
org.apache.juneau.http.annotation.Header @Header} annotations defined on method
- parameters or when the parameter type is the mutable {@link
org.apache.juneau.Value} object.
- The example above shows one of each:
- </p>
- <p class='bcode w800'>
- <ja>@RestGet</ja>(
- path=<js>"/user/login"</js>,
- summary=<js>"Logs user into the system"</js>,
- swagger=<ja>@OpSwagger</ja>(
- tags=<js>"user"</js>
- )
- )
- <jk>public</jk> Ok login(
- <ja>@Query</ja>(
- name=<js>"username"</js>,
- description=<js>"The username for login"</js>,
- required=<jk>true</jk>,
- example=<js>"myuser"</js>
- )
- String <jv>username</jv>,
- <ja>@Query</ja>(
- name=<js>"password"</js>,
- description=<js>"The password for login in
clear text"</js>,
- required=<jk>true</jk>,
- example=<js>"abc123"</js>
- )
- String <jv>password</jv>,
- <ja>@Header</ja>(
- name=<js>"X-Rate-Limit"</js>,
- type=<js>"integer"</js>,
- format=<js>"int32"</js>,
- description=<js>"Calls per hour allowed by the
user."</js>,
- example=<js>"123"</js>
- )
- Value<Integer> <jv>rateLimit</jv>,
- Value<ExpiresAfter> <jv>expiresAfter</jv>,
- RestRequest <jv>req</jv>,
- RestResponse <jv>res</jv>
- ) <jk>throws</jk> InvalidLogin, NotAcceptable {
-
- <jk>if</jk> (! <jf>store</jf>.isValid(<jv>username</jv>,
<jv>password</jv>))
- <jk>throw new</jk> InvalidLogin();
-
- Date <jv>d</jv> = <jk>new</jk>
Date(System.<jsm>currentTimeMillis</jsm>() + 30 * 60 * 1000);
-
<jv>req</jv>.getSession().setAttribute(<js>"login-expires"</js>, d);
- <jv>rateLimit</jv>.set(1000);
- <jv>expiresAfter</jv>.set(<jk>new</jk>
ExpiresAfter(<jv>d</jv>));
- <jk>return</jk> <jsf>OK</jsf>;
- }
- </p>
- <p class='bcode w800'>
- <ja>@Header</ja>(
- name=<js>"X-Expires-After"</js>,
- type=<js>"string"</js>,
- format=<js>"date-time"</js>,
- description=<js>"Date in UTC when token expires"</js>,
- example=<js>"2012-10-21"</js>
- )
- <jk>public static class</jk> ExpiresAfter {
- <jk>private final</jk> Calendar <jf>c</jf>;
- <jk>public</jk> ExpiresAfter(Date <jv>d</jv>) {
- <jk>this</jk>.<jf>c</jf> = <jk>new</jk>
GregorianCalendar();
- <jf>c</jf>.setTime(<jv>d</jv>);
- }
- <jk>public</jk> Calendar toCalendar() {
- <jk>return</jk> <jf>c</jf>;
- }
- }
- </p>
-</div>
-</div><!-- END: 6.15.8 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples -->
+</div><!-- END: 6.15.6 - juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses
-->
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>6.15.9 - Models</a><span
class='update'><b><red>todo</red></b></span></h4>
-<div class='topic'><!-- START: 6.15.9 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerModels -->
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>6.15.7 - Models</a><span
class='update'>updated: <b>9.0.0</b></span></h4>
+<div class='topic'><!-- START: 6.15.7 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerModels -->
<div class='topic'>
<p>
- The {@del
org.apache.juneau.jsonschema.JsonSchemaGenerator#JSONSCHEMA_useBeanDefs}
setting can be used to reduce the size of your
+ The {@link
org.apache.juneau.jsonschema.JsonSchemaGenerator.Builder#useBeanDefs()} setting
can be used to reduce the size of your
generated Swagger JSON files by creating model definitions for
beans and referencing those definitions through <c>$ref</c> attributes.
</p>
<p>
- By default, this flag is enabled when extending from {@link
org.apache.juneau.rest.BasicRestServlet}:
+ This setting is disabled by default, but can be set on the
{@link org.apache.juneau.rest.RestContext.Builder} object:
</p>
<p class='bcode w800'>
- <jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {
-
- <ja>@RestOp</ja>(method=<jsf>OPTIONS</jsf>, path=<js>"/*"</js>,
- ...
- flags={
- <jc>// Use $ref references for bean definitions
to reduce duplication in Swagger.</jc>
- <jsf>JSONSCHEMA_useBeanDefs</jsf>
- }
- )
- <jk>public</jk> Swagger getOptions(RestRequest <jv>req</jv>)
{...}
+ <ja>@HookEvent</ja>(<jsf>INIT</jsf>)
+ <jk>public void</jk> init(RestContext.Builder <jv>builder</jv>) {
+ <jv>builder</jv>.jsonSchemaGenerator().useBeanDefs();
+ }
</p>
<p>
In the Swagger UI, this causes bean definitions to show up in
the Models section at the bottom of the page:
@@ -19028,12 +18544,12 @@
</p>
<img class='bordered w900' src='doc-files/jrs.Swagger.Models.3.png'>
</div>
-</div><!-- END: 6.15.9 - juneau-rest-server.jrs.Swagger.jrs.SwaggerModels -->
+</div><!-- END: 6.15.7 - juneau-rest-server.jrs.Swagger.jrs.SwaggerModels -->
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>6.15.10 -
SwaggerUI.css</a><span class='update'><b><red>todo</red></b></span></h4>
-<div class='topic'><!-- START: 6.15.10 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet -->
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'
id='juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>6.15.8 -
SwaggerUI.css</a></h4>
+<div class='topic'><!-- START: 6.15.8 -
juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet -->
<div class='topic'>
<p>
The look-and-feel of the Swagger UI is controlled via a single
CSS file: <c>SwaggerUI.css</c>.
@@ -19044,12 +18560,12 @@
This file can be modified to change the look-and-feel of your
Swagger UI.
</p>
</div>
-</div><!-- END: 6.15.10 - juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet
-->
+</div><!-- END: 6.15.8 - juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet
-->
</div><!-- END: 6.15 - juneau-rest-server.jrs.Swagger -->
<!--
====================================================================================================
-->
-<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.ExecutionStatistics'
id='juneau-rest-server.jrs.ExecutionStatistics'>6.16 - REST method execution
statistics</a><span class='update'>created: 8.1.3,
<b><red>todo</red></b></span></h3>
+<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.ExecutionStatistics'
id='juneau-rest-server.jrs.ExecutionStatistics'>6.16 - REST method execution
statistics</a><span class='update'>created: 8.1.3, updated:
<b>9.0.0</b></span></h3>
<div class='topic'><!-- START: 6.16 -
juneau-rest-server.jrs.ExecutionStatistics -->
<div class='topic'>
<p>
@@ -19057,7 +18573,33 @@
and <ja>@RestHook</ja> annotated methods on the class.
</p>
<p>
- The statistics are made available via the subpath <c>/stats</c>
as shown below in the <c>HelloWorldResource</c> example:
+ If you extend from {@link
org.apache.juneau.rest.BasicRestServlet} or {@link
org.apache.juneau.rest.BasicRestObject}, then
+ the statics are made available through the REST interface via
the following method:
+ </p>
+ <p class='bcode w800'>
+ <ja>@RestGet</ja>(
+ path=<js>"/stats"</js>,
+ summary=<js>"Timing statistics"</js>,
+ description=<js>"Timing statistics for method invocations on
this resource."</js>
+ )
+ <ja>@HtmlDocConfig</ja>(
+ <jc>// Should override config annotations defined on class.</jc>
+ rank=10,
+ <jc>// Override the nav links for the swagger page.</jc>
+ navlinks={
+ <js>"back: servlet:/"</js>,
+ <js>"json:
servlet:/stats?Accept=text/json&plainText=true"</js>
+ },
+ <jc>// Never show aside contents of page inherited from
class.</jc>
+ aside=<js>"NONE"</js>
+ )
+ <ja>@Override</ja> <jc>/* BasicRestOperations */</jc>
+ <jk>public</jk> RestContextStats getStats(RestRequest <jv>req</jv>) {
+ <jk>return</jk> <jv>req</jv>.getContext().getStats();
+ }
+ </p>
+ <p>
+ Rendered in a browser, it looks like this:
</p>
<img class='bordered w900'
src='doc-files/jrs.ExecutionStatistics.1.png'>
<p>
@@ -19082,7 +18624,7 @@
<!--
====================================================================================================
-->
-<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation'
id='juneau-rest-server.jrs.HtmlDocAnnotation'>6.17 - @HtmlDocConfig</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></h3>
+<h3 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation'
id='juneau-rest-server.jrs.HtmlDocAnnotation'>6.17 - @HtmlDocConfig</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></h3>
<div class='topic'><!-- START: 6.17 - juneau-rest-server.jrs.HtmlDocAnnotation
-->
<div class='topic'>
<p>
@@ -19095,26 +18637,16 @@
<li>{@link org.apache.juneau.rest.annotation.RestOp
@RestOp}-annotated methods.
</ul>
<p>
- The annotation itself is just a convenience for setting
configuration properties set
- on the {@link org.apache.juneau.html.HtmlDocSerializer} class.
- For example, the following two pieces of code are equivalent:
+ For example, the following shows setting the title on a page:
</p>
<p class='bcode w800'>
- <jc>// Title defined via property.</jc>
- <ja>@Rest</ja>(
- properties={
- <ja>@Property</ja>(name=<jsf>HTMLDOC_title</jsf>,
value=<js>"My Resource Page"</js>)
- }
- )
-
- <jc>// Title defined via @HtmlDoc annotation.</jc>
- <ja>@Rest</ja>()
+ <ja>@Rest</ja>
<ja>@HtmlDocConfig</ja>(
title=<js>"My Resource Page"</js>
)
</p>
<p>
- The purpose of these annotation is to populate the HTML
document view which by default consists of the following
+ The purpose of this annotation is to populate the HTML document
view which by default consists of the following
structure:
</p>
<p class='bcode w800'>
@@ -19201,7 +18733,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>6.17.1 - User
Interfaces (UI) vs. Developer Interfaces (DI)</a><span
class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>6.17.1 - User
Interfaces (UI) vs. Developer Interfaces (DI)</a></h4>
<div class='topic'><!-- START: 6.17.1 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI -->
<div class='topic'>
<p>
@@ -19249,19 +18781,16 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>6.17.2 -
Widgets</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>6.17.2 -
Widgets</a><span class='update'>updated: <b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.17.2 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets -->
<div class='topic'>
<p>
The {@link org.apache.juneau.rest.widget.Widget} class allows
you to add arbitrary HTML, CSS, and Javascript
to HTML pages.
- <br>They are registered in the following locations:
+ <br>They are registered in the following location:
</p>
<ul class='javatree'>
- <li class='ja'>{@del
org.apache.juneau.rest.annotation.HtmlDoc#widgets() HtmlDoc(widgets)}
- <li class='jm'>{@del RestContext.Builder#widgets(Class...)}
- <li class='jm'>{@del RestContext.Builder#widgets(Widget...)}
- <li class='jf'>{@del RestContext#REST_widgets}
+ <li class='ja'>{@link
org.apache.juneau.html.annotation.HtmlDocConfig#widgets()
HtmlDocConfig(widgets)}
</ul>
<h5 class='figure'>Example:</h5>
<p class='bcode w800'>
@@ -19333,43 +18862,12 @@
}
}
</p>
- <p>
- The <l>Widget</l> class also defines the following two
convenience methods for loading Javascript and CSS
- files from the classpath or file system.
- </p>
- <ul class='javatree'>
- <li class='jac'>{@link org.apache.juneau.rest.widget.Widget}
- <ul>
- <li class='jm'>{@del
getClasspathResourceAsString(String)}
- <li class='jm'>{@del
getClasspathResourceAsString(String,Locale)}
- </ul>
- </ul>
- <h5 class='figure'>Example:</h5>
- <p class='bcode w800'>
- <jk>public class</jk> MyWidget <jk>extends</jk> Widget {
-
- ...
-
- <ja>@Override</ja> <jc>/* Widget */</jc>
- <jk>public</jk> String getScript(RestRequest <jv>req</jv>)
<jk>throws</jk> Exception {
- <jk>return</jk>
getClasspathResourceAsString(<js>"MyWidget.js"</js>);
- }
-
- <ja>@Override</ja> <jc>/* Widget */</jc>
- <jk>public</jk> String getStyle(RestRequest <jv>req</jv>)
<jk>throws</jk> Exception {
- <jk>return</jk>
getClasspathResourceAsString(<js>"MyWidget.css"</js>);
- }
- }
- </p>
- <ul class='seealso'>
- <li class='jf'>{@del
org.apache.juneau.rest.RestContext#REST_widgets}
- </ul>
</div>
</div><!-- END: 6.17.2 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets -->
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>6.17.3
- Predefined Widgets</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>6.17.3
- Predefined Widgets</a><span class='update'>updated: <b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.17.3 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets -->
<div class='topic'>
<p>
@@ -19440,21 +18938,19 @@
An example of this widget can be found in the
<c>PetStoreResource</c> in the examples that provides a drop-down menu item for
rendering all other supported content types in plain text:
</p>
<p class='bcode w800'>
- <ja>@RestGet</ja>(
- path=<js>"/"</js>,
+ <ja>@RestGet</ja>(path=<js>"/"</js>)
+ <ja>@HtmlDocConfig</ja>(
widgets={
ContentTypeMenuItem.<jk>class</jk>,
},
- htmldoc=<ja>@HtmlDoc</ja>(
- navlinks={
- <js>"up: ..."</js>,
- <js>"options: ..."</js>,
- <js>"$W{QueryMenuItem}"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{ThemeMenuItem}"</js>,
- <js>"source: ..."</js>
- }
- )
+ navlinks={
+ <js>"up: ..."</js>,
+ <js>"options: ..."</js>,
+ <js>"$W{QueryMenuItem}"</js>,
+ <js>"$W{ContentTypeMenuItem}"</js>,
+ <js>"$W{ThemeMenuItem}"</js>,
+ <js>"source: ..."</js>
+ }
)
<jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -19472,7 +18968,7 @@
</p>
<p>
This widget is designed to be used in conjunction with the
{@link org.apache.juneau.rest.converter.Queryable} converter, although
implementations
- can process the query parameters themselves if they wish to do
so by using the {@del RequestQuery#getSearchArgs()}
+ can process the query parameters themselves if they wish to do
so by using the {@link
org.apache.juneau.rest.httppart.RequestQueryParams#getSearchArgs()}
method to retrieve the arguments and process the data
themselves.
</p>
<p>
@@ -19481,20 +18977,20 @@
<p class='bcode w800'>
<ja>@RestGet</ja>(
path=<js>"/"</js>,
+ converters=Queryable.<jk>class</jk>
+ )
+ <ja>@HtmlDocConfig</ja>(
widgets={
QueryMenuItem.<jk>class</jk>,
},
- htmldoc=<ja>@HtmlDoc</ja>(
- navlinks={
- <js>"up: ..."</js>,
- <js>"options: ..."</js>,
- <js>"$W{QueryMenuItem}"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{ThemeMenuItem}"</js>,
- <js>"source: ..."</js>
- }
- ),
- converters=Queryable.<jk>class</jk>
+ navlinks={
+ <js>"up: ..."</js>,
+ <js>"options: ..."</js>,
+ <js>"$W{QueryMenuItem}"</js>,
+ <js>"$W{ContentTypeMenuItem}"</js>,
+ <js>"$W{ThemeMenuItem}"</js>,
+ <js>"source: ..."</js>
+ }
)
<jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -19525,21 +19021,19 @@
a drop-down menu item for rendering all other supported content
types in plain text:
</p>
<p class='bcode w800'>
- <ja>@RestGet</ja>(
- path=<js>"/"</js>,
+ <ja>@RestGet</ja>(path=<js>"/"</js>)
+ <ja>@HtmlDocConfig</ja>(
widgets={
ThemeMenuItem.<jk>class</jk>,
},
- htmldoc=<ja>@HtmlDoc</ja>(
- navlinks={
- <js>"up: ..."</js>,
- <js>"options: ..."</js>,
- <js>"$W{QueryMenuItem}"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{ThemeMenuItem}"</js>,
- <js>"source: ..."</js>
- }
- )
+ navlinks={
+ <js>"up: ..."</js>,
+ <js>"options: ..."</js>,
+ <js>"$W{QueryMenuItem}"</js>,
+ <js>"$W{ContentTypeMenuItem}"</js>,
+ <js>"$W{ThemeMenuItem}"</js>,
+ <js>"source: ..."</js>
+ }
)
<jk>public</jk> Collection<Pet> getPets() {
</p>
@@ -19556,14 +19050,13 @@
Typically it's used in the footer of the page, as shown below
in the <c>AddressBookResource</c> from the examples:
</p>
<p class='bcode w800'>
- <ja>@Rest</ja>(
- path=<js>"/addressBook"</js>,
+ <ja>@Rest</ja>(path=<js>"/addressBook"</js>)
+ <ja>@HtmlDocConfig</ja>(
widgets={
PoweredByJuneau.<jk>class</jk>
},
- htmldoc=<ja>@HtmlDoc</ja>(
- footer=<js>"$W{PoweredByJuneau}"</js>
- )
+ footer=<js>"$W{PoweredByJuneau}"</js>
+ )
</p>
<p>
It renders the following image:
@@ -19611,7 +19104,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>6.17.4 -
UI Customization</a><span class='update'><b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>6.17.4 -
UI Customization</a><span class='update'>updated: <b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.17.4 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization -->
<div class='topic'>
<p>
@@ -19634,32 +19127,6 @@
<p class='bcode w800'>
<ja>@Rest</ja>(
...
- <jc>// HTML-page specific settings</jc>
- htmldoc=<ja>@HtmlDoc</ja>(
-
- <jc>// Default page header contents.</jc>
- header={
- <js>"<h1>$RS{title}</h1>"</js>,
<jc>// Use @Rest(title)</jc>
-
<js>"<h2>$RS{operationSummary,description}</h2>"</js>, <jc>// Use
either @RestOp(summary) or @Rest(description)</jc>
- <js>"$C{REST/header}"</js> <jc>// Extra header
HTML defined in external config file.</jc>
- },
-
- <jc>// Default stylesheet to use for the page.
- // Can be overridden from external config file.
- // Default is DevOps look-and-feel (aka Depression
look-and-feel).</jc>
-
stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>,
-
- <jc>// Default contents to add to the <head>
section of the HTML page.
- // Use it to add a favicon link to the page.</jc>
- head={
- <js>"<link rel='icon'
href='$U{$C{REST/favicon}}'/>"</js>
- },
-
- <jc>// No default page footer contents.
- // Can be overridden from external config file.</jc>
- footer=<js>"$C{REST/footer}"</js>
- ),
-
<jc>// Optional external configuration file.</jc>
config=<js>"$S{juneau.configFile}"</js>,
@@ -19668,21 +19135,41 @@
// By default, we define static files through the external
configuration file.</jc>
staticFiles=<js>"$C{REST/staticFiles}"</js>
)
+ <ja>@HtmlDocConfig</ja>(
+
+ <jc>// Default page header contents.</jc>
+ header={
+ <js>"<h1>$RS{title}</h1>"</js>, <jc>// Use
@Rest(title)</jc>
+
<js>"<h2>$RS{operationSummary,description}</h2>"</js>, <jc>// Use
either @RestOp(summary) or @Rest(description)</jc>
+ <js>"$C{REST/header}"</js> <jc>// Extra header HTML
defined in external config file.</jc>
+ },
+
+ <jc>// Default stylesheet to use for the page.
+ // Can be overridden from external config file.
+ // Default is DevOps look-and-feel (aka Depression
look-and-feel).</jc>
+
stylesheet=<js>"$C{REST/theme,servlet:/htdocs/themes/devops.css}"</js>,
+
+ <jc>// Default contents to add to the <head> section of
the HTML page.
+ // Use it to add a favicon link to the page.</jc>
+ head={
+ <js>"<link rel='icon'
href='$U{$C{REST/favicon}}'/>"</js>
+ },
+
+ <jc>// No default page footer contents.
+ // Can be overridden from external config file.</jc>
+ footer=<js>"$C{REST/footer}"</js>
+ )
+
<jk>public interface</jk> BasicRestConfig {}
</p>
<p class='bcode w800'>
- <ja>@Rest</ja>(
- ...
- htmldoc=<ja>@HtmlDoc</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
- <jc>// Basic page navigation links.</jc>
- navlinks={
- <js>"up: request:/.."</js>,
- <js>"options:
servlet:/?method=OPTIONS"</js>
- }
- )
- ),
- ...
+ <ja>@Rest</ja>(...)
+ <ja>@HtmlDocConfig</ja>(
+ <jc>// Basic page navigation links.</jc>
+ navlinks={
+ <js>"up: request:/.."</js>,
+ <js>"options: servlet:/?method=OPTIONS"</js>
+ }
)
<jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet <jk>implements</jk> BasicRestConfig {...}
</p>
@@ -19691,32 +19178,30 @@
<jk>public abstract class</jk> BasicRestServletGroup <jk>extends</jk>
BasicRestServlet {...}
</p>
<p class='bcode w800'>
- <ja>@Rest</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
- widgets={
- ContentTypeMenuItem.<jk>class</jk>,
- ThemeMenuItem.<jk>class</jk>
- },
- navlinks={
- <js>"options: ?method=OPTIONS"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{ThemeMenuItem}"</js>,
- <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
- },
- aside={
- <js>"<div style='max-width:400px'
class='text'>"</js>,
- <js>" <p>This is an example of
a 'router' page that serves as a jumping-off point to child
resources.</p>"</js>,
- <js>" <p>Resources can be
nested arbitrarily deep through router pages.</p>"</js>,
- <js>" <p>Note the <span
class='link'>options</span> link provided that lets you see the
generated swagger doc for this page.</p>"</js>,
- <js>" <p>Also note the <span
class='link'>sources</span> link on these pages to view the source
code for the page.</p>"</js>,
- <js>" <p>All content on pages
in the UI are serialized POJOs. In this case, it's a serialized array of beans
with 2 properties, 'name' and 'description'.</p>"</js>,
- <js>" <p>Other features (such
as this aside) are added through annotations.</p>"</js>,
- <js>"</div>"</js>
- }
- ),
- ...
- )
- <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletGroup {...}
+ <ja>@Rest</ja>(...)
+ <ja>@HtmlDocConfig</ja>(
+ widgets={
+ ContentTypeMenuItem.<jk>class</jk>,
+ ThemeMenuItem.<jk>class</jk>
+ },
+ navlinks={
+ <js>"options: ?method=OPTIONS"</js>,
+ <js>"$W{ContentTypeMenuItem}"</js>,
+ <js>"$W{ThemeMenuItem}"</js>,
+ <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
+ },
+ aside={
+ <js>"<div style='max-width:400px'
class='text'>"</js>,
+ <js>" <p>This is an example of a 'router' page
that serves as a jumping-off point to child resources.</p>"</js>,
+ <js>" <p>Resources can be nested arbitrarily
deep through router pages.</p>"</js>,
+ <js>" <p>Note the <span
class='link'>options</span> link provided that lets you see the
generated swagger doc for this page.</p>"</js>,
+ <js>" <p>Also note the <span
class='link'>sources</span> link on these pages to view the source
code for the page.</p>"</js>,
+ <js>" <p>All content on pages in the UI are
serialized POJOs. In this case, it's a serialized array of beans with 2
properties, 'name' and 'description'.</p>"</js>,
+ <js>" <p>Other features (such as this aside)
are added through annotations.</p>"</js>,
+ <js>"</div>"</js>
+ }
+ )
+ <jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletGroup {...}
</p>
<p>
@@ -19762,7 +19247,7 @@
<!--
====================================================================================================
-->
-<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>6.17.5 -
Stylesheets</a><span class='update'>updated: 8.1.0,
<b><red>todo</red></b></span></h4>
+<h5 class='topic' onclick='toggle(this)'><a
href='#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'
id='juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>6.17.5 -
Stylesheets</a><span class='update'>updated: 8.1.0,<b>9.0.0</b></span></h4>
<div class='topic'><!-- START: 6.17.5 -
juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets -->
<div class='topic'>
<p>
@@ -19795,12 +19280,11 @@
The {@link org.apache.juneau.rest.BasicRestServlet} class
defines the stylesheet served up as a static file:
<p class='bcode w800'>
<ja>@Rest</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
-
stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>,
- ),
-
staticFiles={<js>"styles:styles"</js>}
)
+ <ja>@HtmlDocConfig</ja>(
+
stylesheet=<js>"$C{REST/stylesheet,servlet:/styles/devops.css}"</js>,
+ )
<jk>public abstract class</jk> BasicRestServlet <jk>extends</jk>
RestServlet {...}
</p>
<p>
@@ -19814,11 +19298,11 @@
</p>
<p class='bcode w800'>
<ja>@Rest</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
- stylesheet=<js>"servlet:/my-styles/my-style.css}"</js>,
- ),
staticFiles={<js>"my-styles:my-styles"</js>}
)
+ <ja>@HtmlDocConfig</ja>(
+ stylesheet=<js>"servlet:/my-styles/my-style.css}"</js>,
+ )
<jk>public class</jk> MyResourceBaseClass <jk>extends</jk>
BasicRestServlet {...}
</p>
<p>
@@ -19830,19 +19314,19 @@
In case you're curious about how the menu item works, it's
defined via a widget:
</p>
<p class='bcode w800'>
- <ja>@Rest</ja>(
- htmldoc=<ja>@HtmlDoc</ja>(
- widgets={
- PoweredByApache.<jk>class</jk>,
- ContentTypeMenuItem.<jk>class</jk>,
- StyleMenuItem.<jk>class</jk>
- },
- navlinks={
- <js>"options: ?method=OPTIONS"</js>,
- <js>"$W{ContentTypeMenuItem}"</js>,
- <js>"$W{StyleMenuItem}"</js>,
- <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
- },
+ <ja>@Rest</ja>(...)
+ <ja>@HtmlDocConfig</ja>(
+ widgets={
+ PoweredByApache.<jk>class</jk>,
+ ContentTypeMenuItem.<jk>class</jk>,
+ StyleMenuItem.<jk>class</jk>
+ },
+ navlinks={
+ <js>"options: ?method=OPTIONS"</js>,
+ <js>"$W{ContentTypeMenuItem}"</js>,
+ <js>"$W{StyleMenuItem}"</js>,
+ <js>"source:
$C{Source/gitHub}/org/apache/juneau/examples/rest/$R{servletClassSimple}.java"</js>
+ }
)
<jk>public class</jk> RootResources <jk>extends</jk>
BasicRestServletJenaGroup {...}
</p>
diff --git a/juneau-doc/src/main/javadoc/resources/docs.txt
b/juneau-doc/src/main/javadoc/resources/docs.txt
index 6ee1798..80fc1d1 100644
--- a/juneau-doc/src/main/javadoc/resources/docs.txt
+++ b/juneau-doc/src/main/javadoc/resources/docs.txt
@@ -251,7 +251,7 @@ jrs.AdditionalInformation =
#juneau-rest-server.jrs.RestOpAnnotatedMethods.jrs.A
jrs.AnnotatedClasses = #juneau-rest-server.jrs.AnnotatedClasses, Overview >
juneau-rest-server > @Rest-Annotated Classes
jrs.BasicRestServlet =
#juneau-rest-server.jrs.AnnotatedClasses.jrs.BasicRestServlet, Overview >
juneau-rest-server > @Rest-Annotated Classes > BasicRestServlet/BasicRestObject
jrs.BasicRestServletGroup =
#juneau-rest-server.jrs.AnnotatedClasses.jrs.BasicRestServletGroup, Overview >
juneau-rest-server > @Rest-Annotated Classes >
BasicRestServletGroup/BasicRestObjectGroup
-jrs.BasicRestServletSwagger =
#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger, Overview >
juneau-rest-server > Swagger > BasicRestServlet
+jrs.BasicRestServletSwagger =
#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger, Overview >
juneau-rest-server > Swagger > BasicRestServlet/BasicRestObject
jrs.BasicSwaggerInfo = #juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo,
Overview > juneau-rest-server > Swagger > Basic Swagger Info
jrs.BuiltInParameters = #juneau-rest-server.jrs.BuiltInParameters, Overview >
juneau-rest-server > Built-in Parameters
jrs.ClientVersioning = #juneau-rest-server.jrs.ClientVersioning, Overview >
juneau-rest-server > Client Versioning
@@ -303,9 +303,7 @@ jrs.SvlVariables = #juneau-rest-server.jrs.SvlVariables,
Overview > juneau-rest-
jrs.Swagger = #juneau-rest-server.jrs.Swagger, Overview > juneau-rest-server >
Swagger
jrs.SwaggerModels = #juneau-rest-server.jrs.Swagger.jrs.SwaggerModels,
Overview > juneau-rest-server > Swagger > Models
jrs.SwaggerOperations = #juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations,
Overview > juneau-rest-server > Swagger > Operations
-jrs.SwaggerParameterExamples =
#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples, Overview >
juneau-rest-server > Swagger > Parameter Examples
jrs.SwaggerParameters = #juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters,
Overview > juneau-rest-server > Swagger > Parameters
-jrs.SwaggerResponseExamples =
#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples, Overview >
juneau-rest-server > Swagger > Response Examples
jrs.SwaggerResponses = #juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses,
Overview > juneau-rest-server > Swagger > Responses
jrs.SwaggerStylesheet = #juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet,
Overview > juneau-rest-server > Swagger > SwaggerUI.css
jrs.SwaggerTags = #juneau-rest-server.jrs.Swagger.jrs.SwaggerTags, Overview >
juneau-rest-server > Swagger > Tags
diff --git a/juneau-doc/src/main/javadoc/resources/fragments/toc.html
b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
index 125752a..6552583 100644
--- a/juneau-doc/src/main/javadoc/resources/fragments/toc.html
+++ b/juneau-doc/src/main/javadoc/resources/fragments/toc.html
@@ -234,27 +234,25 @@
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.SvlVariables'>SVL
Variables</a><span class='update'>updated: <b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.StaticFiles'>Static files</a><span
class='update'>updated: <b>9.0.0</b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.ClientVersioning'>Client
Versioning</a><span class='update'>updated: <b>9.0.0</b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger'>Swagger</a><span
class='update'><b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger'>Swagger</a></p>
<ol>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>BasicRestServlet</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>Basic
Swagger Info</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>Tags</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>Operations</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>Parameters</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameterExamples'>Parameter
Examples</a><span class='update'>updated: 8.1.0,
<b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>Responses</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponseExamples'>Response
Examples</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>Models</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>SwaggerUI.css</a><span
class='update'><b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.BasicRestServletSwagger'>BasicRestServlet/BasicRestObject</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.BasicSwaggerInfo'>Basic
Swagger Info</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerTags'>Tags</a></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerOperations'>Operations</a></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerParameters'>Parameters</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerResponses'>Responses</a></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerModels'>Models</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.Swagger.jrs.SwaggerStylesheet'>SwaggerUI.css</a></p>
</ol>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.ExecutionStatistics'>REST method
execution statistics</a><span class='update'>created: 8.1.3,
<b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation'>@HtmlDocConfig</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.ExecutionStatistics'>REST method
execution statistics</a><span class='update'>created: 8.1.3, updated:
<b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation'>@HtmlDocConfig</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
<ol>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>User
Interfaces (UI) vs. Developer Interfaces (DI)</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>Widgets</a><span
class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>Predefined
Widgets</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>UI
Customization</a><span class='update'><b><red>todo</red></b></span></p>
- <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>Stylesheets</a><span
class='update'>updated: 8.1.0, <b><red>todo</red></b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUIvsDI'>User
Interfaces (UI) vs. Developer Interfaces (DI)</a></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlWidgets'>Widgets</a><span
class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlPredefinedWidgets'>Predefined
Widgets</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlUiCustomization'>UI
Customization</a><span class='update'>updated: <b>9.0.0</b></span></p>
+ <li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.HtmlDocAnnotation.jrs.HtmlStylesheets'>Stylesheets</a><span
class='update'>updated: 8.1.0,<b>9.0.0</b></span></p>
</ol>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.DefaultHeaders'>Default
Headers</a><span class='update'><b><red>todo</red></b></span></p>
<li><p><a class='doclink'
href='{OVERVIEW_URL}#juneau-rest-server.jrs.LoggingAndDebugging'>Logging /
Debugging</a><span class='update'>created: 8.1.0, updated: 8.2.0,
<b><red>todo</red></b></span></p>
