org.apache.juneau.rest.annotation.ResourceSwagger Maven / Gradle / Ivy
// ***************************************************************************************************************************
// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file *
// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file *
// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance *
// * with the License. You may obtain a copy of the License at *
// * *
// * http://www.apache.org/licenses/LICENSE-2.0 *
// * *
// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an *
// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the *
// * specific language governing permissions and limitations under the License. *
// ***************************************************************************************************************************
package org.apache.juneau.rest.annotation;
import org.apache.juneau.rest.*;
/**
* Extended annotation for {@link RestResource#swagger() @RestResource.swagger()}.
*/
public @interface ResourceSwagger {
/**
* 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" ).
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /info/termsOfService.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTermsOfService(RestRequest)}
* method.
*/
String termsOfService() default "";
/**
* Optional contact information for the exposed API.
*
*
* It is used to populate the Swagger contact field and to display on HTML pages.
*
*
* A simplified JSON 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:'[email protected]'}" or
* "MyServlet.contact = {name:'John Smith',email:'[email protected]'}" ).
*
*
Example:
*
* @RestResource (
* swagger=@MethodSwagger (
* contact="{name:'John Smith',email:'[email protected]'}"
* )
* )
*
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /info/contact.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getContact(RestRequest)} method.
*/
String contact() default "";
/**
* Optional license information for the exposed API.
*
*
* It is used to populate the Swagger license field and to display on HTML pages.
*
*
* A simplified JSON 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:
*
* @RestResource (
* swagger=@MethodSwagger (
* license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"
* )
* )
*
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /info/license.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getLicense(RestRequest)} method.
*/
String license() default "";
/**
* 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" ).
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /info/version.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getVersion(RestRequest)} method.
*/
String version() default "";
/**
* Optional tagging information for the exposed API.
*
*
* It is used to populate the Swagger tags field and to display on HTML pages.
*
*
* A simplified JSON 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:
*
* @RestResource (
* swagger=@MethodSwagger (
* tags="[{name:'Foo',description:'Foobar'}]"
* )
* )
*
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /tags.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getTags(RestRequest)} method.
*/
String tags() default "";
/**
* Optional external documentation information for the exposed API.
*
*
* It is used to populate the Swagger external documentation field and to display on HTML pages.
*
*
* A simplified JSON string with the following fields:
*
* {
* description: string,
* url: string
* }
*
*
*
* 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:
*
* @RestResource (
* swagger=@MethodSwagger (
* externalDocs="{url:'http://juneau.apache.org'}"
* )
* )
*
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
* See {@link RestContext#getVarResolver()} for the list of supported variables.
*
*
* Corresponds to the swagger field /tags.
*
*
* The programmatic equivalent to this annotation is the {@link RestInfoProvider#getExternalDocs(RestRequest)}
* method.
*/
String externalDocs() default "";
}