Package org.apache.juneau.rest.annotation

Annotation Type Swagger

@Retention(RUNTIME) public @interface Swagger
Extended annotation for @Rest(swagger).
See Also:

  • Element Details

    • contact

      Contact contact
      Defines the swagger field /info/contact.

      A Swagger string with the following fields:

      { name: string, url: string, email: string }

      The default value pulls the description from the contact entry in the servlet resource bundle. (e.g. "contact = {name:'John Smith',email:'john.smith@foo.bar'}" or "MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}").

      Example:

      @Rest( swagger=@Swagger( contact="{name:'John Smith',email:'john.smith@foo.bar'}" ) )

      Notes:
      • The format is a Swagger object.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.http.annotation.Contact

    • description

      String[] description
      Defines the swagger field /info/description.
      Example:

      @Rest( swagger=@Swagger( description={ "This is a sample server Petstore server based on the Petstore sample at Swagger.io.", "You can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>." } ) )

      Notes:
      • The format is plain text.
        Multiple lines are concatenated with newlines.
      • The precedence of lookup for this field is:
        1. {resource-class}.description property in resource bundle.
        2. description() on this class, then any parent classes.
        3. Value defined in Swagger JSON file.
        4. Rest.description() on this class, then any parent classes.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • externalDocs

      ExternalDocs externalDocs
      Defines the swagger field /externalDocs.

      It is used to populate the Swagger external documentation field and to display on HTML pages. *

      The default value pulls the description from the externalDocs entry in the servlet resource bundle. (e.g. "externalDocs = {url:'http://juneau.apache.org'}" or "MyServlet.externalDocs = {url:'http://juneau.apache.org'}").

      Example:

      @Rest( swagger=@Swagger( externalDocs=@ExternalDocs(url="http://juneau.apache.org") ) )

      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.annotation.ExternalDocs

    • license

      License license
      Defines the swagger field /info/license.

      It is used to populate the Swagger license field and to display on HTML pages.

      A Swagger string with the following fields:

      { name: string, url: string }

      The default value pulls the description from the license entry in the servlet resource bundle. (e.g. "license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}" or "MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}").

      Example:

      @Rest( swagger=@Swagger( license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}" ) )

      Notes:
      • The format is a Swagger object.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.http.annotation.License

    • tags

      Tag[] tags
      Defines the swagger field /tags. Optional tagging information for the exposed API.

      It is used to populate the Swagger tags field and to display on HTML pages.

      A Swagger string with the following fields:

      [ { name: string, description: string, externalDocs: { description: string, url: string } } ]

      The default value pulls the description from the tags entry in the servlet resource bundle. (e.g. "tags = [{name:'Foo',description:'Foobar'}]" or "MyServlet.tags = [{name:'Foo',description:'Foobar'}]").

      Example:

      @Rest( swagger=@Swagger( tags="[{name:'Foo',description:'Foobar'}]" ) )

      Notes:
      • The format is a Swagger array.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • termsOfService

      String[] termsOfService
      Defines the swagger field /info/termsOfService. Optional servlet terms-of-service for this API.

      It is used to populate the Swagger terms-of-service field.

      The default value pulls the description from the termsOfService entry in the servlet resource bundle. (e.g. "termsOfService = foo" or "MyServlet.termsOfService = foo").

      Notes:
      • The format is plain text.
        Multiple lines are concatenated with newlines.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • title

      String[] title
      Defines the swagger field /info/title.
      Example:

      @Rest( swagger=@Swagger( title="Petstore application" ) )

      Notes:
      • The format is plain-text.
        Multiple lines are concatenated with newlines.
      • The precedence of lookup for this field is:
        1. {resource-class}.title property in resource bundle.
        2. title() on this class, then any parent classes.
        3. Value defined in Swagger JSON file.
        4. Rest.title() on this class, then any parent classes.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}

    • value

      String[] value
      Free-form value for the swagger of a resource.

      This is a Swagger object that makes up the swagger information for this resource.

      The following are completely equivalent ways of defining the swagger description of a resource:

      // Normal @Rest( swagger=@Swagger( title="Petstore application", description={ "This is a sample server Petstore server based on the Petstore sample at Swagger.io.", "You can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>." }, contact=@Contact( name="John Smith", email="john@smith.com" ), license=@License( name="Apache 2.0", url="http://www.apache.org/licenses/LICENSE-2.0.html" ), version="2.0", termsOfService="You are on your own.", tags={ @Tag( name="Java", description="Java utility", externalDocs=@ExternalDocs( description="Home page", url="http://juneau.apache.org" ) } }, externalDocs=@ExternalDocs( description="Home page", url="http://juneau.apache.org" ) ) )

      // Free-form @Rest( swagger=@Swagger({ "title: 'Petstore application',", "description: 'This is a sample server Petstore server based on the Petstore sample at Swagger.io.\nYou can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>.',", "contact:{", "name: 'John Smith',", "email: 'john@smith.com'", "},", "license:{", "name: 'Apache 2.0',", "url: 'http://www.apache.org/licenses/LICENSE-2.0.html'", "},", "version: '2.0',", "termsOfService: 'You are on your own.',", "tags:[", "{", "name: 'Java',", "description: 'Java utility',", "externalDocs:{", "description: 'Home page',", "url: 'http://juneau.apache.org'", "}", "}", "],", "externalDocs:{", "description: 'Home page',", "url: 'http://juneau.apache.org'", "}" }) )

      // Free-form with variables @Rest( swagger=@Swagger("$F{MyResourceSwagger.json}") )

      The reasons why you may want to use this field include:

      • You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file.
      • You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
      Notes:
      • The format is a Swagger object.
      • The leading/trailing { } characters are optional.
        The following two example are considered equivalent:

        @Swagger("{title:'Petstore application'}")

        @Swagger("title:'Petstore application'")

      • Multiple lines are concatenated with newlines so that you can format the value to be readable.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      • Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
      Returns:
      The annotation value.
      Default:
      {}

    • version

      String version
      Defines the swagger field /info/version. Provides the version of the application API (not to be confused with the specification version).

      It is used to populate the Swagger version field and to display on HTML pages.

      The default value pulls the description from the version entry in the servlet resource bundle. (e.g. "version = 2.0" or "MyServlet.version = 2.0").

      Notes:
      • The format is plain text.
      • Supports SVL Variables (e.g. "$L{my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      ""