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