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 @Rest(swagger) annotation. The real PetStoreResource (juneau-petstore-core) keeps things simple and only sets title/description via @Rest without a swagger= member, so the example below is a self-contained illustrative resource — not literally the shipping PetStoreResource — showing the various ways the @Rest(swagger) annotation can be populated.

Example: pulling Swagger info from an external file

@Rest(
    path="/myResource",
    title="My REST API",
    ...
    swagger=@Swagger("$F{MyResource.json}"),
    ...
)
public class MyResource extends BasicRestServlet {...}

In this particular case, the Swagger is pulled in from a localized Swagger JSON file located alongside the resource class using the $F variable.

MyResource.json

{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "My REST API",
        "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 $F variable allows for request-locale-sensitive name matching so that you can provide localized Swagger information. The $F variable simply expands to a string to fill the @Swagger(value) annotation. You could equivalently embed JSON directly into your annotation like so:

@Rest(
    path="/myResource",
    title="My REST API",
    ...
    swagger=@Swagger(
        // Raw JSON5.
        // Values are concatenated.
        "{",
            "swagger: '2.0',",
            "version: '1.0.0',",
            ...
        "}"
    ),
    ...
)
public class MyResource extends BasicRestServlet {...}

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

@Rest(
    path="/myResource",
    title="My REST API",
    ...
    swagger=@Swagger(
        version="1.0.0",
        title="My REST API",
        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 MyResource extends BasicRestServlet {...}

All annotations support SVL Variables, so you could for example pull localized strings from resource bundles using $L variables.

@Rest(
    path="/myResource",
    title="My REST API",
    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 MyResource extends BasicRestServlet {...}

A third option is to define your Swagger information in your @Rest(messages) resource bundle using predefined Swagger keywords:

MyResource.version = 1.0.0
MyResource.title = My REST API
MyResource.termsOfService = You are on your own.
MyResource.contact = {name:'Juneau Development Team', email:'dev@juneau.apache.org',...}
MyResource.license = {name:'Apache 2.0',...}
MyResource.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