org.apache.juneau.rest.annotation.Parameter 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.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;
import java.lang.annotation.*;
/**
* Annotation used in conjunction with {@link MethodSwagger#parameters()} to identify content and header descriptions
* on specific method requests.
*
* Example:
*
* @RestMethod (
* name="*" ,
* swagger=@MethodSwagger(
* parameters={
* @Parameter (in="header" , name="Range" , description="$L{ContentRange.description}" )
* }
* )
* )
* public void doAnything(RestRequest req, RestResponse res, @Method String method) {
* ...
* }
*
*/
@Documented
@Target(PARAMETER)
@Retention(RUNTIME)
@Inherited
public @interface Parameter {
/**
* The location of the parameter.
*
*
* Possible values are:
*
* "query"
* "header"
* "path"
* "formData"
* "body"
*
*/
String in() default "";
/**
* The name of the parameter (e.g. "Content-Range" ).
*
*
* Parameter names are case sensitive.
* If in is "path" , the name field MUST correspond to the associated path segment from the
* path field in the Paths Object.
* See Path Templating for further
* information.
* For all other cases, the name corresponds to the parameter name used based on the in property.
*/
String name() default "";
/**
* Parameter description (e.g. "Indicates the range returned when Range header is present in the request" ).
*
*
* A brief description of the parameter.
* This could contain examples of use.
* GFM syntax can be used
* for rich text representation.
*
*
* The default value pulls the description from the description entry in the servlet resource bundle.
* (e.g. "myMethod.res.[code].[category].[name] = foo" or
* "MyServlet.myMethod.res.[code].[category].[name] = foo" ).
*/
String description() default "";
/**
* Determines whether this parameter is mandatory.
*
*
* If the parameter is in "path" , this property is required and its value MUST be true .
* Otherwise, the property MAY be included and its default value is false .
*/
boolean required() default false;
/**
* The schema defining the type used for the body parameter.
*
*
* Only applicable for in of type "body" .
*
*
* The schema is a JSON object specified here.
*
*
Example:
*
* @RestMethod (
* parameters={
* @Parameter (
* in="header" ,
* name="Foo" ,
* schema="{format:'string',title:'Foo header',description:'Header that contains the Foo value.'}" )
* }
* )
* public void doAnything() {
*
*/
String schema() default "";
/**
* The type of the parameter.
*
*
* The value MUST be one of "string" , "number" , "integer" , "boolean" ,
* "array" or "file" .
* If type is "file" , the consumes MUST be either "multipart/form-data" ,
* "application/x-www-form-urlencoded" or both and the parameter MUST be in "formData" .
*/
String type() default "string";
/**
* The extending format for the previously mentioned type.
*
*
* See Data Type Formats for further
* details.
*/
String format() default "";
/**
* Sets the ability to pass empty-valued parameters.
*
*
* This is valid only for either query or formData parameters and allows you to send a
* parameter with a name only or an empty value.
* Default value is false .
*/
boolean allowEmptyValue() default false;
/**
* Required if type is "array" .
*
*
* Describes the type of items in the array.
*
*
Example:
*
* @RestMethod (
* parameters={
* @Parameter (
* in="header" ,
* name="Foo" ,
* type="array" ,
* items="{type:'string',collectionFormat:'csv'}" )
* }
* )
* public void doAnything() {
*
*
*
* See Items Object for further details.
*/
String items() default "";
/**
* Determines the format of the array if type array is used.
*
*
* Possible values are:
*
* "csv" - comma separated values "foo,bar" .
* "ssv" - space separated values "foo bar" .
* "tsv" - tab separated values "foo\tbar" .
* "pipes" - pipe separated values "foo|bar" .
* "multi" - corresponds to multiple parameter instances instead of multiple values for a single
* instance "foo=bar&foo=baz" .
* This is valid only for parameters in "query" or "formData" .
*
* Default value is "csv" .
*/
String collectionFormat() default "";
/**
* Declares the value of the parameter that the server will use if none is provided.
*
*
* For example a "count" to control the number of results per page might default to 100 if not supplied by the
* client in the request.
* (Note: "default" has no meaning for required parameters.)
* See
* http://json-schema.org/latest/json-schema-validation.html#anchor101.
* Unlike JSON Schema this value MUST conform to the defined type for this parameter.
*/
String _default() default "";
}