001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.rest.annotation; 018 019import static java.lang.annotation.RetentionPolicy.*; 020 021import java.lang.annotation.*; 022 023import org.apache.juneau.annotation.*; 024 025/** 026 * Extended annotation for {@link RestOp#swagger() RestOp.swagger()}. 027 * 028 * <h5 class='section'>See Also:</h5><ul> 029 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> 030 * </ul> 031 */ 032@Retention(RUNTIME) 033public @interface OpSwagger { 034 035 /** 036 * Defines the swagger field <c>/paths/{path}/{method}/consumes</c>. 037 * 038 * <p> 039 * Use this value to override the supported <c>Content-Type</c> media types defined by the parsers defined via {@link RestOp#parsers()}. 040 * 041 * <h5 class='section'>Notes:</h5><ul> 042 * <li class='note'> 043 * The format is either a comma-delimited list of simple strings or a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> array. 044 * <li class='note'> 045 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 046 * <li class='note'> 047 * Values defined on this annotation override values defined for the method in the class swagger. 048 * </ul> 049 * 050 * @return The annotation value. 051 */ 052 String[] consumes() default {}; 053 054 /** 055 * Defines the swagger field <c>/paths/{path}/{method}/deprecated</c>. 056 * 057 * <h5 class='section'>Example:</h5> 058 * <p class='bjava'> 059 * <ja>@RestGet</ja>( 060 * swagger=<ja>@OpSwagger</ja>( 061 * deprecated=<jk>true</jk> 062 * ) 063 * ) 064 * </p> 065 * 066 * <h5 class='section'>Notes:</h5><ul> 067 * <li class='note'> 068 * The format is boolean. 069 * <li class='note'> 070 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 071 * <li class='note'> 072 * Values defined on this annotation override values defined for the method in the class swagger. 073 * <li class='note'> 074 * If not specified, set to <js>"true"</js> if the method is annotated with {@link Deprecated @Deprecated} 075 * </ul> 076 * 077 * @return The annotation value. 078 */ 079 String deprecated() default ""; 080 081 /** 082 * Defines the swagger field <c>/paths/{path}/{method}/description</c>. 083 * 084 * <h5 class='section'>Notes:</h5><ul> 085 * <li class='note'> 086 * The format is plain text. 087 * <br>Multiple lines are concatenated with newlines. 088 * <li class='note'> 089 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 090 * <li class='note'> 091 * Values defined on this annotation override values defined for the method in the class swagger. 092 * <li class='note'> 093 * If not specified, the value is pulled from {@link RestOp#description()}. 094 * </ul> 095 * 096 * @return The annotation value. 097 */ 098 String[] description() default {}; 099 100 /** 101 * Defines the swagger field <c>/paths/{path}/{method}/externalDocs</c>. 102 * 103 * <h5 class='section'>Example:</h5> 104 * <p class='bjava'> 105 * <ja>@RestGet</ja>( 106 * swagger=<ja>@OpSwagger</ja>( 107 * externalDocs=<ja>@ExternalDocs</ja>(url=<js>"http://juneau.apache.org"</js>) 108 * ) 109 * ) 110 * </p> 111 * 112 * <h5 class='section'>Notes:</h5><ul> 113 * <li class='note'> 114 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 115 * <li class='note'> 116 * Values defined on this annotation override values defined for the method in the class swagger. 117 * </ul> 118 * 119 * @return The annotation value. 120 */ 121 ExternalDocs externalDocs() default @ExternalDocs; 122 123 /** 124 * Defines the swagger field <c>/paths/{path}/{method}/operationId</c>. 125 * 126 * <h5 class='section'>Notes:</h5><ul> 127 * <li class='note'> 128 * The format is plain text. 129 * <li class='note'> 130 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 131 * <li class='note'> 132 * Values defined on this annotation override values defined for the method in the class swagger. 133 * <li class='note'> 134 * If not specified, the value used is the Java method name. 135 * </ul> 136 * 137 * @return The annotation value. 138 */ 139 String operationId() default ""; 140 141 /** 142 * Defines the swagger field <c>/paths/{path}/{method}/parameters</c>. 143 * 144 * <p> 145 * This annotation is provided for documentation purposes and is used to populate the method <js>"parameters"</js> 146 * column on the Swagger page. 147 * 148 * <h5 class='section'>Example:</h5> 149 * <p class='bjava'> 150 * <ja>@RestPost</ja>( 151 * path=<js>"/{a}"</js>, 152 * description=<js>"This is my method."</js>, 153 * swagger=<ja>@OpSwagger</ja>( 154 * parameters={ 155 * <js>"{in:'path', name:'a', description:'The \\'a\\' attribute'},"</js>, 156 * <js>"{in:'query', name:'b', description:'The \\'b\\' parameter', required:true},"</js>, 157 * <js>"{in:'body', description:'The HTTP content'},"</js>, 158 * <js>"{in:'header', name:'D', description:'The \\'D\\' header'}"</js> 159 * } 160 * ) 161 * ) 162 * </p> 163 * 164 * <h5 class='section'>Notes:</h5><ul> 165 * <li class='note'> 166 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> array consisting of the concatenated individual strings. 167 * <br>The leading and trailing <js>'['</js> and <js>']'</js> characters are optional. 168 * <li class='note'> 169 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 170 * <li> 171 * </ul> 172 * 173 * @return The annotation value. 174 */ 175 String[] parameters() default {}; 176 177 /** 178 * Defines the swagger field <c>/paths/{path}/{method}/consumes</c>. 179 * 180 * <p> 181 * Use this value to override the supported <c>Accept</c> media types defined by the serializers defined via {@link RestOp#serializers()}. 182 * 183 * <h5 class='section'>Notes:</h5><ul> 184 * <li class='note'> 185 * The format is either a comma-delimited list of simple strings or a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> array. 186 * <li class='note'> 187 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 188 * <li class='note'> 189 * Values defined on this annotation override values defined for the method in the class swagger. 190 * </ul> 191 * 192 * @return The annotation value. 193 */ 194 String[] produces() default {}; 195 196 /** 197 * Defines the swagger field <c>/paths/{path}/{method}/responses</c>. 198 * 199 * <p> 200 * This annotation is provided for documentation purposes and is used to populate the method <js>"responses"</js> 201 * column on the Swagger page. 202 * 203 * <h5 class='section'>Example:</h5> 204 * <p class='bjava'> 205 * <ja>@RestGet</ja>( 206 * path=<js>"/"</js>, 207 * swagger=<ja>@OpSwagger</ja>( 208 * responses={ 209 * <js>"200:{ description:'Okay' },"</js>, 210 * <js>"302:{ description:'Thing wasn't found here', headers={Location:{description:'The place to find the thing.'}}}"</js> 211 * } 212 * ) 213 * ) 214 * </p> 215 * 216 * <h5 class='section'>Notes:</h5><ul> 217 * <li class='note'> 218 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> objc consisting of the concatenated individual strings. 219 * <br>The leading and trailing <js>'{'</js> and <js>'}'</js> characters are optional. 220 * <li class='note'> 221 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 222 * </ul> 223 * 224 * @return The annotation value. 225 */ 226 String[] responses() default {}; 227 228 /** 229 * Defines the swagger field <c>/paths/{path}/{method}/schemes</c>. 230 * 231 * <h5 class='section'>Notes:</h5><ul> 232 * <li class='note'> 233 * The format is either a comma-delimited list of simple strings or a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> array. 234 * <li class='note'> 235 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 236 * <li class='note'> 237 * Values defined on this annotation override values defined for the method in the class swagger. 238 * </ul> 239 * 240 * @return The annotation value. 241 */ 242 String[] schemes() default {}; 243 244 /** 245 * Defines the swagger field <c>/paths/{path}/{method}/summary</c>. 246 * 247 * <h5 class='section'>Notes:</h5><ul> 248 * <li class='note'> 249 * The format is plain text. 250 * <br>Multiple lines are concatenated with newlines. 251 * <li class='note'> 252 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 253 * <li class='note'> 254 * Values defined on this annotation override values defined for the method in the class swagger. 255 * <li class='note'> 256 * If not specified, the value is pulled from {@link RestOp#summary()}. 257 * </ul> 258 * 259 * @return The annotation value. 260 */ 261 String[] summary() default {}; 262 263 /** 264 * Optional tagging information for the exposed API. 265 * 266 * <p> 267 * Used to populate the Swagger tags field. 268 * 269 * <p> 270 * A comma-delimited list of tags for API documentation control. 271 * <br>Tags can be used for logical grouping of operations by resources or any other qualifier. 272 * 273 * <h5 class='section'>Example:</h5> 274 * <p class='bjava'> 275 * <ja>@RestGet</ja>( 276 * swagger=<ja>@OpSwagger</ja>( 277 * tags=<js>"foo,bar"</js> 278 * ) 279 * ) 280 * </p> 281 * 282 * <h5 class='section'>Notes:</h5><ul> 283 * <li class='note'> 284 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 285 * <li class='note'> 286 * Corresponds to the swagger field <c>/paths/{path}/{method}/tags</c>. 287 * </ul> 288 * 289 * @return The annotation value. 290 */ 291 String[] tags() default {}; 292 293 /** 294 * Free-form value for the swagger of a resource method. 295 * 296 * <p> 297 * This is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object that makes up the swagger information for this resource method. 298 * 299 * <p> 300 * The following are completely equivalent ways of defining the swagger description of a resource method: 301 * <p class='bjava'> 302 * <jc>// Normal</jc> 303 * <ja>@RestPost</ja>( 304 * path=<js>"/pet"</js>, 305 * swagger=<ja>@OpSwagger</ja>( 306 * summary=<js>"Add pet"</js>, 307 * description=<js>"Adds a new pet to the store"</js>, 308 * tags=<js>"pet"</js>, 309 * externalDocs=<ja>@ExternalDocs</ja>( 310 * description=<js>"Home page"</js>, 311 * url=<js>"http://juneau.apache.org"</js> 312 * ) 313 * ) 314 * ) 315 * </p> 316 * <p class='bjava'> 317 * <jc>// Free-form</jc> 318 * <ja>@RestPost</ja>( 319 * path=<js>"/pet"</js>, 320 * swagger=<ja>@OpSwagger</ja>({ 321 * <js>"summary: 'Add pet',"</js>, 322 * <js>"description: 'Adds a new pet to the store',"</js>, 323 * <js>"tags: ['pet'],"</js>, 324 * <js>"externalDocs:{"</js>, 325 * <js>"description: 'Home page',"</js>, 326 * <js>"url: 'http://juneau.apache.org'"</js>, 327 * <js>"}"</js> 328 * }) 329 * ) 330 * </p> 331 * <p class='bjava'> 332 * <jc>// Free-form with variables</jc> 333 * <ja>@RestPost</ja>( 334 * path=<js>"/pet"</js>, 335 * swagger=<ja>@OpSwagger</ja>(<js>"$L{addPetSwagger}"</js>) 336 * ) 337 * </p> 338 * <p class='bini'> 339 * <mc>// Contents of MyResource.properties</mc> 340 * <mk>addPetSwagger</mk> = <mv>{ summary: "Add pet", description: "Adds a new pet to the store", tags: ["pet"], externalDocs:{ description: "Home page", url: "http://juneau.apache.org" } }</mv> 341 * </p> 342 * 343 * <p> 344 * The reasons why you may want to use this field include: 345 * <ul> 346 * <li>You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file. 347 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 348 * </ul> 349 * 350 * <h5 class='section'>Notes:</h5><ul> 351 * <li class='note'> 352 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 353 * <li class='note'> 354 * The leading/trailing <c>{ }</c> characters are optional. 355 * <br>The following two example are considered equivalent: 356 * <p class='bjava'> 357 * <ja>@OpSwagger</ja>(<js>"{summary: 'Add pet'}"</js>) 358 * </p> 359 * <p class='bjava'> 360 * <ja>@OpSwagger</ja>(<js>"summary: 'Add pet'"</js>) 361 * </p> 362 * <li class='note'> 363 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 364 * <li class='note'> 365 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 366 * <li class='note'> 367 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 368 * </ul> 369 * 370 * @return The annotation value. 371 */ 372 String[] value() default {}; 373}