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.rest.*;
/**
* Extended annotation for {@link RestMethod#swagger() RestMethod.swagger()}.
*/
public @interface MethodSwagger {
/**
* Optional external documentation information for the exposed API.
*
*
* Used to populate the Swagger external documentation field.
*
*
* A simplified JSON string with the following fields:
*
* {
* description: string,
* url: string
* }
*
*
*
* The default value pulls the description from the (className.?)[javaMethodName].externalDocs entry in
* the servlet resource bundle.
* (e.g. "MyClass.myMethod.externalDocs = {url:'http://juneau.apache.org'}" or
* "myMethod.externalDocs = {url:'http://juneau.apache.org'}" ).
*
*
Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* "{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 /paths/{path}/{method}/externalDocs.
*/
String externalDocs() 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.
*
*
* The default value pulls the description from the (className.?)[javaMethodName].tags entry in the
* servlet resource bundle.
* (e.g. "MyClass.myMethod.tags = foo,bar" or "myMethod.tags = foo,bar" ).
*
*
Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* tags="foo,bar"
* )
* )
*
*
*
* 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 /paths/{path}/{method}/tags.
*/
String tags() default "";
/**
* Optional deprecated flag for the exposed API.
*
*
* Used to populate the Swagger deprecated field.
*
*
* The default value pulls the description from the (className.?)[javaMethodName].deprecated entry in
* the servlet resource bundle.
* (e.g. "MyClass.myMethod.deprecated = true" or "myMethod.deprecated = foo,bar" ).
*
*
Example:
*
* @RestMethod (
* swagger=@MethodSwagger (
* deprecated=true
* )
* )
*
*
*
* 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 /paths/{path}/{method}/deprecated.
*/
boolean deprecated() default false;
/**
* Optional parameter descriptions.
*
*
* 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" ),
* }
* )
* )
*
*
*
* This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in
* this case the strings are internationalized.
*
* MyClass.myMethod.description = This is my method.
* MyClass.myMethod.req.path.a.description = The 'a' attribute
* MyClass.myMethod.req.query.b.description = The 'b' parameter
* MyClass.myMethod.req.body.description = The HTTP content
* MyClass.myMethod.req.header.d.description = The 'D' header
*
*
*
* As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support
* English), and use resource bundles if you need to support localization.
*
*
* 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 /paths/{path}/{method}/parameters.
*/
Parameter[] parameters() default {};
/**
* Optional output description.
*
*
* 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" )
* }
* )
* }
* )
* )
*
*
*
* This is functionally equivalent to specifying the following keys in the resource bundle for the class, except in
* this case the strings are internationalized.
*
* MyClass.myMethod.res.200.description = OK
* MyClass.myMethod.res.302.description = Thing wasn't found here
* MyClass.myMethod.res.302.header.Location.description = The place to find the thing
*
*
*
* As a general rule, use annotations when you don't care about internationalization (i.e. you only want to support
* English), and use resource bundles if you need to support localization.
*
*
* This field can contain variables (e.g. "$L{my.localized.variable}" ).
*
See {@link RestContext#getVarResolver()} for the list of supported variables.
*/
Response[] responses() default {};
}