{new} Parameter Examples

The model select box in the parameters can be expanded to show examples:

The examples for query/form-data/path/header parameters can be defined using the example attribute on your annotated parameters as shown here:

@RestMethod( ... ) public Collection<Pet> getPets( @Query( name="s", description={ "Search.", "Key/value pairs representing column names and search tokens.", "'*' and '?' can be used as meta-characters in string fields.", "'>', '>=', '<', and '<=' can be used as limits on numeric and date fields.", "Date fields can be matched with partial dates (e.g. '2018' to match any date in the year 2018)." }, type="array", collectionFormat="csv", example="Bill*,birthDate>2000" ) ... ) throws NotAcceptable { ... }

This value gets converted to an x-examples attribute in your parameter information:

{ "swagger": "2.0", "paths": { "/pet": { "get": { "operationId": "getPets", "summary": "All pets in the store", "parameters": [ { "in": "query", "name": "s", ... "x-examples": { "example": "?s=Bill*,birthDate>2000" } }, ...

Examples for request bodies includes all supported Content-Type values:

These are based on the parsers registered on your servlet or method.

Selecting any of the content types shows you a representative example for the POJO:

There are several options for defining examples for request bodies:

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.

Example:

// A JSON representation of a PetCreate object. @Body( example="{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}" )

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.

Example:

// A JSON representation of a PetCreate object. @Body( examples={ "'application/json':'{name:\\'Doggie\\',species:\\'Dog\\'}',", "'text/uon':'(name:Doggie,species=Dog)'" } )

The Swagger generator uses these to create an x-examples entry in your generated Swagger:

"/pet": { "post": { "operationId": "postPet", "summary": "Add a new pet to the store", "parameters": [ { "in": "body", "description": "Pet object to add to the store", "required": true, "schema": { "$ref": "#/definitions/PetCreate" }, "x-examples": { "application/json": "{\n\t\"name\": \"Doggie\",\n\t\"species\": \"Dog\",\n\t\"price\": 9.99,\n\t\"tags\": [\n...", "application/json+simple": "{\n\tname: 'Doggie',\n\tspecies: 'Dog',\n\tprice: 9.99,\n\ttags: [\n\t\t'friendly...", "text/xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<object>\n\t<name>Doggie</name&...", "text/html+stripped": "<table>\n\t<tr>\n\t\t<td>name</td>\n\t\t<td>Doggie</t...", "text/uon": "(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)", "application/x-www-form-urlencoded": "name=Doggie\n&species=Dog\n&price=9.99\n&tags=@(\n\tfriendly,\n\tcute\n)", "text/openapi": "(\n\tname=Doggie,\n\tspecies=Dog,\n\tprice=9.99,\n\ttags=@(\n\t\tfriendly,\n\t\tcute\n\t)\n)", "octal/msgpack": "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...", "text/plain": "{name:'Doggie',species:'Dog',price:9.99,tags:['friendly','cute']}", "text/xml+rdf": "<rdf:RDF\n xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"\n xmlns:j=\"ht...", "text/turtle": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.a...", "text/n-triple": "_:A59722791X3aX165d321a2b4X3aXX2dX7fca <http://www.apache.org/juneaubp/name> \"Doggie...", "text/n3": "@prefix jp: <http://www.apache.org/juneaubp/> .\n@prefix j: <http://www.apach..." } } ],

Another option is to define these directly in your resource Swagger JSON file, or via {@link oajr.annotation.RestResource#swagger() @RestResource(swagger)}/{@link oajr.annotation.RestMethod#swagger() @RestMethod(swagger)}.

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:

public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig { @RestMethod(name=OPTIONS, path="/*", ... properties={ // Add x-example to the following types: @Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"), }, ... ) public Swagger getOptions(RestRequest req) {...}

Examples can be defined via static methods, fields, and annotations on the classes themselves.

Examples:

// Annotation on class. @Example("{name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}") public class PetCreate { ... }

// Annotation on static method. public class PetCreate { @Example public static PetCreate sample() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static method with specific name 'example'. public class PetCreate { public static PetCreate example() { return new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); } }

// Static field. public class PetCreate { @Example public static PetCreate EXAMPLE = new PetCreate("Doggie", 9.99f, "Dog", new String[] {"friendly","cute"}); }

Examples can also be specified via generic properties as well using the {@link oaj.BeanContext#BEAN_examples} property at either the class or method level.

Example:

// Examples defined at class level. @RestResource( properties={ @Property( name=BEAN_examples, value="{'org.apache.juneau.examples.rest.petstore.PetCreate': {name:'Doggie',price:9.99,species:'Dog',tags:['friendly','cute']}}" ) } )

See Also: