org.apache.juneau.rest.annotation.MethodSwagger 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.http.annotation.*;
/**
* Extended annotation for {@link RestMethod#swagger() RestMethod.swagger()}.
*
* See Also:
*
* - {@doc juneau-rest-server.Swagger}
*
*/
public @interface MethodSwagger {
/**
* Defines the swagger field /paths/{path}/{method}/summary.
*
* Notes:
*
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (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 RestMethod#summary()}.
*
*/
String[] summary() default {};
/**
* Defines the swagger field /paths/{path}/{method}/description.
*
* Notes:
*
* -
* The format is plain text.
*
Multiple lines are concatenated with newlines.
* -
* Supports {@doc DefaultRestSvlVariables}
* (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 RestMethod#description()}.
*
*/
String[] description() default {};
/**
* Defines the swagger field /paths/{path}/{method}/operationId.
*
* Notes:
*
* -
* The format is plain text.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (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.
*
*/
String operationId() default "";
/**
* Defines the swagger field /paths/{path}/{method}/schemes.
*
* Notes:
*
* -
* The format is either a comma-delimited list of simple strings or a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*/
String[] schemes() default {};
/**
* Defines the swagger field /paths/{path}/{method}/deprecated.
*
* Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* deprecated=true
* )
* )
*
*
* Notes:
*
* -
* The format is boolean.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (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}
*
*/
String deprecated() default "";
/**
* 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 RestMethod#parsers()}.
*
*
Notes:
*
* -
* The format is either a comma-delimited list of simple strings or a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*/
String[] consumes() 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 RestMethod#serializers()}.
*
*
Notes:
*
* -
* The format is either a comma-delimited list of simple strings or a {@doc juneau-marshall.JsonDetails.SimplifiedJson} array.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*/
String[] produces() default {};
/**
* Defines the swagger field /paths/{path}/{method}/externalDocs.
*
* Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* externalDocs=@ExternalDocs (url="http://juneau.apache.org" )
* )
* )
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
*/
ExternalDocs externalDocs() default @ExternalDocs;
/**
* 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:
*
* @RestMethod (
* name=POST , path="/{a}" ,
* description="This is my method." ,
* swagger=@MethodSwagger (
* parameters={
* @Parameter (in="path" , name="a" , description="The 'a' attribute" ),
* @Parameter (in="query" , name="b" , description="The 'b' parameter" , required=true ),
* @Parameter (in="body" , description="The HTTP content" ),
* @Parameter (in="header" , name="D" , description="The 'D' header" ),
* }
* )
* )
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
*
*/
String[] parameters() 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:
*
* @RestMethod (
* name=GET , path="/" ,
* swagger=@MethodSwagger (
* responses={
* @Response (200),
* @Response (
* value=302,
* description="Thing wasn't found here" ,
* headers={
* @Parameter (name="Location" , description="The place to find the thing" )
* }
* )
* }
* )
* )
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
*
*/
String[] responses() 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:
*
* @RestMethod (
* swagger=@MethodSwagger (
* tags="foo,bar"
* )
* )
*
*
* Notes:
*
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Corresponds to the swagger field
/paths/{path}/{method}/tags.
*
*/
String[] tags() default {};
/**
* Defines the swagger field /paths/{path}/{method}.
*
*
* Used for free-form Swagger documentation of a REST Java method.
*
*
Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* "tags:['pet']," ,
* "security:[ { petstore_auth:['write:pets','read:pets'] } ]"
* )
* )
*
*
* Notes:
*
* -
* The format is a {@link JsonSerializer#DEFAULT_LAX Simple-JSON} object.
*
Multiple lines are concatenated with newlines.
*
Comments and whitespace are ignored.
*
The leading and trailing '{' /'}' characters are optional.
* -
* Supports {@doc DefaultRestSvlVariables}
* (e.g.
"$L{my.localized.variable}" ).
* -
* Values defined on this annotation override values defined for the method in the class swagger.
*
-
*
*
*/
/**
* Free-form value for the swagger of a resource method.
*
*
* This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} 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
* @RestMethod (
* name="POST" ,
* path="/pet" ,
* swagger=@MethodSwagger (
* 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
* @RestMethod (
* name="POST" ,
* path="/pet" ,
* swagger=@MethodSwagger ({
* "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
* @RestMethod (
* name="POST" ,
* path="/pet" ,
* swagger=@MethodSwagger ("$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 body 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 {@doc juneau-marshall.JsonDetails.SimplifiedJson} object.
*
-
* The leading/trailing
{ } characters are optional.
*
The following two example are considered equivalent:
*
* @MethodSwagger ("{summary: 'Add pet'}" )
*
*
* @MethodSwagger ("summary: 'Add pet'" )
*
* -
* Multiple lines are concatenated with newlines so that you can format the value to be readable.
*
-
* Supports {@doc DefaultRestSvlVariables}
* (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.
*
*/
String[] value() default {};
}