org.apache.juneau.rest.annotation.OpSwagger 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 static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
import org.apache.juneau.annotation.*;
/**
* Extended annotation for {@link RestOp#swagger() RestOp.swagger()}.
*
* See Also:
* - Swagger
*
*/
@Retention(RUNTIME)
public @interface OpSwagger {
/**
* Defines the swagger field /paths/{path}/{method}/consumes .
*
*
* Use this value to override the supported Content-Type media types defined by the parsers defined via {@link RestOp#parsers()}.
*
*
Notes:
* -
* The format is either a comma-delimited list of simple strings or a Swagger array.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*
* @return The annotation value.
*/
String[] consumes() default {};
/**
* Defines the swagger field /paths/{path}/{method}/deprecated .
*
* Example:
*
* @RestGet (
* swagger=@OpSwagger (
* deprecated=true
* )
* )
*
*
* Notes:
* -
* The format is boolean.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
-
* If not specified, set to
"true" if the method is annotated with {@link Deprecated @Deprecated}
*
*
* @return The annotation value.
*/
String deprecated() default "";
/**
* Defines the swagger field /paths/{path}/{method}/description .
*
* Notes:
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
-
* If not specified, the value is pulled from {@link RestOp#description()}.
*
*
* @return The annotation value.
*/
String[] description() default {};
/**
* Defines the swagger field /paths/{path}/{method}/externalDocs .
*
* Example:
*
* @RestGet (
* swagger=@OpSwagger (
* externalDocs=@ExternalDocs (url="http://juneau.apache.org" )
* )
* )
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*
* @return The annotation value.
*/
ExternalDocs externalDocs() default @ExternalDocs;
/**
* Defines the swagger field /paths/{path}/{method}/operationId .
*
* Notes:
* -
* The format is plain text.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
-
* If not specified, the value used is the Java method name.
*
*
* @return The annotation value.
*/
String operationId() default "";
/**
* Defines the swagger field /paths/{path}/{method}/parameters .
*
*
* This annotation is provided for documentation purposes and is used to populate the method "parameters"
* column on the Swagger page.
*
*
Example:
*
* @RestPost (
* path="/{a}" ,
* description="This is my method." ,
* swagger=@OpSwagger (
* parameters={
* "{in:'path', name:'a', description:'The \\'a\\' attribute'}," ,
* "{in:'query', name:'b', description:'The \\'b\\' parameter', required:true}," ,
* "{in:'body', description:'The HTTP content'}," ,
* "{in:'header', name:'D', description:'The \\'D\\' header'}"
* }
* )
* )
*
*
* Notes:
* -
* The format is a Swagger array consisting of the concatenated individual strings.
*
The leading and trailing '[' and ']' characters are optional.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
*
*
* @return The annotation value.
*/
String[] parameters() default {};
/**
* Defines the swagger field /paths/{path}/{method}/consumes .
*
*
* Use this value to override the supported Accept media types defined by the serializers defined via {@link RestOp#serializers()}.
*
*
Notes:
* -
* The format is either a comma-delimited list of simple strings or a Swagger array.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*
* @return The annotation value.
*/
String[] produces() default {};
/**
* Defines the swagger field /paths/{path}/{method}/responses .
*
*
* This annotation is provided for documentation purposes and is used to populate the method "responses"
* column on the Swagger page.
*
*
Example:
*
* @RestGet (
* path="/" ,
* swagger=@OpSwagger (
* responses={
* "200:{ description:'Okay' }," ,
* "302:{ description:'Thing wasn't found here', headers={Location:{description:'The place to find the thing.'}}}"
* }
* )
* )
*
*
* Notes:
* -
* The format is a Swagger objc consisting of the concatenated individual strings.
*
The leading and trailing '{' and '}' characters are optional.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
*
*
* @return The annotation value.
*/
String[] responses() default {};
/**
* Defines the swagger field /paths/{path}/{method}/schemes .
*
* Notes:
* -
* The format is either a comma-delimited list of simple strings or a Swagger array.
*
-
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*
* @return The annotation value.
*/
String[] schemes() default {};
/**
* Defines the swagger field /paths/{path}/{method}/summary .
*
* Notes:
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
-
* If not specified, the value is pulled from {@link RestOp#summary()}.
*
*
* @return The annotation value.
*/
String[] summary() default {};
/**
* Optional tagging information for the exposed API.
*
*
* Used to populate the Swagger tags field.
*
*
* A comma-delimited list of tags for API documentation control.
*
Tags can be used for logical grouping of operations by resources or any other qualifier.
*
*
Example:
*
* @RestGet (
* swagger=@OpSwagger (
* tags="foo,bar"
* )
* )
*
*
* Notes:
* -
* Supports SVL Variables (e.g.
"$L{my.localized.variable}" ).
* -
* Corresponds to the swagger field
/paths/{path}/{method}/tags .
*
*
* @return The annotation value.
*/
String[] tags() default {};
/**
* Free-form value for the swagger of a resource method.
*
*
* This is a Swagger object that makes up the swagger information for this resource method.
*
*
* The following are completely equivalent ways of defining the swagger description of a resource method:
*
* // Normal
* @RestPost (
* path="/pet" ,
* swagger=@OpSwagger (
* summary="Add pet" ,
* description="Adds a new pet to the store" ,
* tags="pet" ,
* externalDocs=@ExternalDocs (
* description="Home page" ,
* url="http://juneau.apache.org"
* )
* )
* )
*
*
* // Free-form
* @RestPost (
* path="/pet" ,
* swagger=@OpSwagger ({
* "summary: 'Add pet'," ,
* "description: 'Adds a new pet to the store'," ,
* "tags: ['pet']," ,
* "externalDocs:{" ,
* "description: 'Home page'," ,
* "url: 'http://juneau.apache.org'" ,
* "}"
* })
* )
*
*
* // Free-form with variables
* @RestPost (
* path="/pet" ,
* swagger=@OpSwagger ("$L{addPetSwagger}" )
* )
*
*
* // Contents of MyResource.properties
* addPetSwagger = { summary: "Add pet", description: "Adds a new pet to the store", tags: ["pet"], externalDocs:{ description: "Home page", url: "http://juneau.apache.org" } }
*
*
*
* 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:
*
* @OpSwagger ("{summary: 'Add pet'}" )
*
*
* @OpSwagger ("summary: 'Add pet'" )
*
* -
* 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.
*
*
* @return The annotation value.
*/
String[] value() default {};
}