| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| {8.1.0-updated} |
| Parameter Examples |
| |
| <p> |
| The <c>model</c> select box in the parameters can be expanded to show examples: |
| </p> |
| <img class='bordered w900' src='doc-files/juneau-rest-server.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='bpcode w800'> |
| <ja>@RestMethod</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> |
| ) |
| ... |
| ) <jk>throws</jk> NotAcceptable { |
| ... |
| } |
| </p> |
| <p> |
| This value gets converted to an <c>x-examples</c> attribute in your parameter information: |
| </p> |
| <p class='bpcode 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/juneau-rest-server.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/juneau-rest-server.Swagger.Parameters.4.png'> |
| <p> |
| There are several options for defining examples for request bodies: |
| </p> |
| <ul class='spaced-list'> |
| <li> |
| {@link oaj.http.annotation.Body#example() @Body(example)} annotation. |
| <li> |
| {@link 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>@ResourceSwagger</ja>(value)</c>/<c><ja>@MethodSwagger</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 {@link 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='bpcode 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 {@link 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='bpcode 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='bpcode 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.RestMethod#swagger() @RestMethod(swagger)}. |
| </p> |
| <p> |
| Juneau also supports auto-generation of JSON-Schema directly from POJO classes. |
| By default, the generated swagger uses to the {@link oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo JSONSCHEMA_addExamplesTo} |
| setting to automatically add examples to beans, collections, arrays, and maps: |
| </p> |
| <p class='bpcode w800'> |
| <jk>public abstract class</jk> BasicRestServlet <jk>extends</jk> RestServlet <jk>implements</jk> BasicRestConfig { |
| |
| <ja>@RestMethod</ja>(name=<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='bpcode 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='bpcode 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='bpcode 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='bpcode 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#BEAN_examples} property or {@link oaj.annotation.BeanConfig#examples() @BeanConfig(examples)} annotation at either the class or method level. |
| </p> |
| <h5 class='figure'>Example:</h5> |
| <p class='bpcode 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} |
| <ul> |
| <li class='jf'>{@link oaj.BeanContext#BEAN_examples BEAN_examples} |
| </ul> |
| <li class='jc'>{@link oaj.jsonschema.JsonSchemaGenerator} |
| <ul> |
| <li class='jf'>{@link oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_addExamplesTo JSONSCHEMA_addExamplesTo} |
| <li class='jf'>{@link oaj.jsonschema.JsonSchemaGenerator#JSONSCHEMA_allowNestedExamples JSONSCHEMA_allowNestedExamples} |
| </ul> |
| </ul> |