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