Let's look at the various parts of the Petstore application Swagger UI to see how they are defined.

The top part of the page shows general information about the REST interface:

The information is pulled from the {@link oajr.annotation.RestResource#swagger() @RestResource(swagger)} annotation.

org.apache.juneau.examples.rest.petstore.PetStoreResource

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger("$F{PetStoreResource.json}"), ... ) public class PetStoreResource extends BasicRestServletJena {...}

In this particular case, the Swagger is pulled in from a localized Swagger JSON file located in the org.apache.juneau.examples.rest.petstore package using the {@link oajr.vars.FileVar $F} variable.

PetStoreResource.json

{ "swagger": "2.0", "info": { "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "You are on your own.", "contact": { "name": "Juneau Development Team", "email": "dev@juneau.apache.org", "url": "http://juneau.apache.org" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "Find out more about Juneau", "url": "http://juneau.apache.org" }, ... }

Note that the {@link oajr.vars.FileVar $F} variable allows for request-locale-sensitive name matching so that you can provide localized Swagger information.

The {@link oajr.vars.FileVar $F} variable simply expands to a string to fill the {@link oajr.annotation.ResourceSwagger#value() @ResourceSwagger(value)} annotation. You could equivalently embed JSON directly into your annotation like so:

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger( // Raw Simplified JSON. // Values are concatenated. "{", "swagger: '2.0',", "version: '1.0.0',", ... "}" ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

However, a more typical (and less error-prone) scenario is to define all of your Swagger as annotations:

@RestResource( path="/petstore", title="Petstore application", ... swagger=@ResourceSwagger( version="1.0.0", title="Swagger Petstore", termsOfService="You are on your own.", contact=@Contact( name="Juneau Development Team", email="dev@juneau.apache.org", url="http://juneau.apache.org" ), license=@License( name="Apache 2.0", url="http://www.apache.org/licenses/LICENSE-2.0.html" ), externalDocs=@ExternalDocs( description="Find out more about Juneau", url="http://juneau.apache.org" ) ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

All annotations support {@doc DefaultRestSvlVariables SVL variables}, so you could for example pull localized strings from resource bundles using {@link oajr.vars.LocalizationVar $L} variables.

@RestResource( path="/petstore", title="Petstore application", messages="nls/MyMessages", ... swagger=@ResourceSwagger( version="1.0.0", title="$L{myTitle}", termsOfService="$L{myTermsOfService}", contact=@Contact( name="$L{myTeam}", email="dev@juneau.apache.org", url="http://juneau.apache.org" ), license=@License( name="Apache 2.0", url="http://www.apache.org/licenses/LICENSE-2.0.html" ), externalDocs=@ExternalDocs( description="$L{myExternalDocsDescription}", url="http://juneau.apache.org" ) ), ... ) public class PetStoreResource extends BasicRestServletJena {...}

A third option is to define your Swagger information in your {@link oajr.annotation.RestResource#messages @RestResource(messages)} resource bundle using predefined Swagger keywords:

PetStoreResource.version = 1.0.0 PetStoreResource.title = Swagger Petstore PetStoreResource.termsOfService = You are on your own. PetStoreResource.contact = {name:'Juneau Development Team', email:'dev@juneau.apache.org',...} PetStoreResource.license = {name:'Apache 2.0',...} PetStoreResource.externalDocs = {description:'Find out more about Juneau',...}

Information defined in multiple locations are merged into a single set of data. When the same information is provided in multiple locations, the following order-of-precedence is used:

1. Java annotations
2. Resource bundle
3. Swagger JSON file