Basic Swagger Info

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.Rest#swagger() @Rest(swagger)} annotation.

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

@Rest( 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:

@Rest( 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:

@Rest( 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 RestSvlVariables SVL variables}, so you could for example pull localized strings from resource bundles using {@link oajr.vars.LocalizationVar $L} variables.

@Rest( 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.Rest#messages @Rest(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