001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.rest.annotation; 014 015import static java.lang.annotation.ElementType.*; 016import static java.lang.annotation.RetentionPolicy.*; 017 018import java.lang.annotation.*; 019 020/** 021 * Annotation used in conjunction with {@link MethodSwagger#parameters() @MethodSwagger.parameters()} to identify 022 * content and header descriptions on specific method requests. 023 * 024 * <h5 class='section'>Example:</h5> 025 * <p class='bcode'> 026 * <ja>@RestMethod</ja>( 027 * name=<js>"*"</js>, 028 * swagger=@MethodSwagger( 029 * parameters={ 030 * <ja>@Parameter</ja>(in=<js>"header"</js>, name=<js>"Range"</js>, description=<js>"$L{ContentRange.description}"</js>) 031 * } 032 * ) 033 * ) 034 * <jk>public void</jk> doAnything(RestRequest req, RestResponse res, <ja>@Method</ja> String method) { 035 * ... 036 * } 037 * </p> 038 * 039 * <h5 class='section'>See Also:</h5> 040 * <ul> 041 * <li class='link'>{@doc juneau-rest-server.Swagger} 042 * </ul> 043 */ 044@Documented 045@Target(PARAMETER) 046@Retention(RUNTIME) 047@Inherited 048@Deprecated 049public @interface Parameter { 050 051 /** 052 * Declares the value of the parameter that the server will use if none is provided. 053 * 054 * <p> 055 * For example a "count" to control the number of results per page might default to 100 if not supplied by the 056 * client in the request. 057 * (Note: "default" has no meaning for required parameters.) 058 * See <a class="doclink" href="http://json-schema.org/latest/json-schema-validation.html#anchor101"> 059 * http://json-schema.org/latest/json-schema-validation.html#anchor101</a>. 060 * Unlike JSON Schema this value MUST conform to the defined <code>type</code> for this parameter. 061 */ 062 String _default() default ""; 063 064 /** 065 * Sets the ability to pass empty-valued parameters. 066 * 067 * <p> 068 * This is valid only for either <code>query</code> or <code>formData</code> parameters and allows you to send a 069 * parameter with a name only or an empty value. 070 * Default value is <jk>false</jk>. 071 */ 072 boolean allowEmptyValue() default false; 073 074 /** 075 * Determines the format of the array if type array is used. 076 * 077 * <p> 078 * Possible values are: 079 * <ul> 080 * <li><js>"csv"</js> - comma separated values <js>"foo,bar"</js>. 081 * <li><js>"ssv"</js> - space separated values <js>"foo bar"</js>. 082 * <li><js>"tsv"</js> - tab separated values <js>"foo\tbar"</js>. 083 * <li><js>"pipes"</js> - pipe separated values <js>"foo|bar"</js>. 084 * <li><js>"multi"</js> - corresponds to multiple parameter instances instead of multiple values for a single 085 * instance <js>"foo=bar&foo=baz"</js>. 086 * This is valid only for parameters <code>in</code> <js>"query"</js> or <js>"formData"</js>. 087 * </ul> 088 * Default value is <js>"csv"</js>. 089 */ 090 String collectionFormat() default ""; 091 092 /** 093 * Parameter description (e.g. <js>"Indicates the range returned when Range header is present in the request"</js>). 094 * 095 * <p> 096 * A brief description of the parameter. 097 * This could contain examples of use. 098 * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used 099 * for rich text representation. 100 * 101 * <p> 102 * The default value pulls the description from the <code>description</code> entry in the servlet resource bundle. 103 * (e.g. <js>"myMethod.res.[code].[category].[name] = foo"</js> or 104 * <js>"MyServlet.myMethod.res.[code].[category].[name] = foo"</js>). 105 */ 106 String description() default ""; 107 108 /** 109 * The extending format for the previously mentioned <code>type</code>. 110 * 111 * <p> 112 * See <a class="doclink" href="http://swagger.io/specification/#dataTypeFormat">Data Type Formats</a> for further 113 * details. 114 */ 115 String format() default ""; 116 117 /** 118 * The location of the parameter. 119 * 120 * <p> 121 * Possible values are: 122 * <ul> 123 * <li><js>"query"</js> 124 * <li><js>"header"</js> 125 * <li><js>"path"</js> 126 * <li><js>"formData"</js> 127 * <li><js>"body"</js> 128 * </ul> 129 */ 130 String in() default ""; 131 132 /** 133 * Required if <code>type</code> is <js>"array"</js>. 134 * 135 * <p> 136 * Describes the type of items in the array. 137 * 138 * <h5 class='section'>Example:</h5> 139 * <p class='bcode'> 140 * <ja>@RestMethod</ja>( 141 * parameters={ 142 * <ja>@Parameter</ja>( 143 * in=<js>"header"</js>, 144 * name=<js>"Foo"</js>, 145 * type=<js>"array"</js>, 146 * items=<js>"{type:'string',collectionFormat:'csv'}"</js>) 147 * } 148 * ) 149 * <jk>public void</jk> doAnything() { 150 * </p> 151 * 152 * <p> 153 * See <a class="doclink" href="http://swagger.io/specification/#itemsObject">Items Object</a> for further details. 154 */ 155 String items() default ""; 156 157 /** 158 * The name of the parameter (e.g. <js>"Content-Range"</js>). 159 * 160 * <p> 161 * Parameter names are case sensitive. 162 * If <code>in</code> is <js>"path"</js>, the name field MUST correspond to the associated path segment from the 163 * <code>path</code> field in the <a class="doclink" 164 * href="http://swagger.io/specification/#pathsObject">Paths Object</a>. 165 * See <a class="doclink" href="http://swagger.io/specification/#pathTemplating">Path Templating</a> for further 166 * information. 167 * For all other cases, the name corresponds to the parameter name used based on the <code>in</code> property. 168 */ 169 String name() default ""; 170 171 /** 172 * Determines whether this parameter is mandatory. 173 * 174 * <p> 175 * If the parameter is <code>in</code> <js>"path"</js>, this property is required and its value MUST be <jk>true</jk>. 176 * Otherwise, the property MAY be included and its default value is <jk>false</jk>. 177 */ 178 boolean required() default false; 179 180 /** 181 * The schema defining the type used for the body parameter. 182 * 183 * <p> 184 * Only applicable for <code>in</code> of type <js>"body"</js>. 185 * 186 * <p> 187 * The schema is a JSON object specified <a class="doclink" href="http://swagger.io/specification/#schemaObject">here</a>. 188 * 189 * <h5 class='section'>Example:</h5> 190 * <p class='bcode'> 191 * <ja>@RestMethod</ja>( 192 * parameters={ 193 * <ja>@Parameter</ja>( 194 * in=<js>"header"</js>, 195 * name=<js>"Foo"</js>, 196 * schema=<js>"{format:'string',title:'Foo header',description:'Header that contains the Foo value.'}"</js>) 197 * } 198 * ) 199 * <jk>public void</jk> doAnything() { 200 * </p> 201 */ 202 String schema() default ""; 203 204 /** 205 * The type of the parameter. 206 * 207 * <p> 208 * The value MUST be one of <js>"string"</js>, <js>"number"</js>, <js>"integer"</js>, <js>"boolean"</js>, 209 * <js>"array"</js> or <js>"file"</js>. 210 * If type is <js>"file"</js>, the consumes MUST be either <js>"multipart/form-data"</js>, 211 * <js>"application/x-www-form-urlencoded"</js> or both and the parameter MUST be in <js>"formData"</js>. 212 */ 213 String type() default "string"; 214}