{title:'Basic Swagger Info', updated:'9.0.0'}

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=@Swagger("$F{PetStoreResource.json}"), | ... | ) | public class PetStoreResource extends BasicRestServlet {...}

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.Swagger#value() @Swagger(value)} annotation. You could equivalently embed JSON directly into your annotation like so:

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

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=@Swagger( | 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 BasicRestServlet {...}

All annotations support 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=@Swagger( | 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 BasicRestServlet {...}

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