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.server; 018 019import static java.lang.annotation.RetentionPolicy.*; 020 021import java.lang.annotation.*; 022 023import org.apache.juneau.commons.*; 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">REST Server 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">REST Server 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">REST Server 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 * Excludes this operation from the published Swagger / OpenAPI specification. 102 * 103 * <p> 104 * When set to <jk>true</jk>, this operation is skipped during Swagger / OpenAPI generation: 105 * neither the path entry nor any sibling HTTP method on the same path is emitted unless 106 * another operation contributes to it. This is useful for endpoints that are not API-meaningful 107 * (e.g. greedy {@code /*} static-file handlers, {@code /favicon.ico}, internal probes) where 108 * documenting the operation would just be noise. 109 * 110 * <h5 class='section'>Example:</h5> 111 * <p class='bjava'> 112 * <ja>@RestGet</ja>( 113 * path=<js>"/static/*"</js>, 114 * swagger=<ja>@OpSwagger</ja>( 115 * ignore=<jk>true</jk> 116 * ) 117 * ) 118 * </p> 119 * 120 * <h5 class='section'>Notes:</h5><ul> 121 * <li class='note'> 122 * Default is <jk>false</jk> — operations are emitted by default. 123 * <li class='note'> 124 * Schema-level {@code ignore} flags (on bean fields / parameters) are separate from this 125 * method-level flag — this one suppresses the entire operation; schema-level flags 126 * suppress individual fields within a referenced schema. 127 * </ul> 128 * 129 * @return The annotation value. 130 */ 131 boolean ignore() default false; 132 133 /** 134 * Defines the swagger field <c>/paths/{path}/{method}/externalDocs</c>. 135 * 136 * <h5 class='section'>Example:</h5> 137 * <p class='bjava'> 138 * <ja>@RestGet</ja>( 139 * swagger=<ja>@OpSwagger</ja>( 140 * externalDocs=<ja>@ExternalDocs</ja>(url=<js>"http://juneau.apache.org"</js>) 141 * ) 142 * ) 143 * </p> 144 * 145 * <h5 class='section'>Notes:</h5><ul> 146 * <li class='note'> 147 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 148 * <li class='note'> 149 * Values defined on this annotation override values defined for the method in the class swagger. 150 * </ul> 151 * 152 * @return The annotation value. 153 */ 154 ExternalDocs externalDocs() default @ExternalDocs; 155 156 /** 157 * Defines the swagger field <c>/paths/{path}/{method}/operationId</c>. 158 * 159 * <h5 class='section'>Notes:</h5><ul> 160 * <li class='note'> 161 * The format is plain text. 162 * <li class='note'> 163 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 164 * <li class='note'> 165 * Values defined on this annotation override values defined for the method in the class swagger. 166 * <li class='note'> 167 * If not specified, the value used is the Java method name. 168 * </ul> 169 * 170 * @return The annotation value. 171 */ 172 String operationId() default ""; 173 174 /** 175 * Defines the swagger field <c>/paths/{path}/{method}/parameters</c>. 176 * 177 * <p> 178 * This annotation is provided for documentation purposes and is used to populate the method <js>"parameters"</js> 179 * column on the Swagger page. 180 * 181 * <h5 class='section'>Example:</h5> 182 * <p class='bjava'> 183 * <ja>@RestPost</ja>( 184 * path=<js>"/{a}"</js>, 185 * description=<js>"This is my method."</js>, 186 * swagger=<ja>@OpSwagger</ja>( 187 * parameters={ 188 * <js>"{in:'path', name:'a', description:'The \\'a\\' attribute'},"</js>, 189 * <js>"{in:'query', name:'b', description:'The \\'b\\' parameter', required:true},"</js>, 190 * <js>"{in:'body', description:'The HTTP content'},"</js>, 191 * <js>"{in:'header', name:'D', description:'The \\'D\\' header'}"</js> 192 * } 193 * ) 194 * ) 195 * </p> 196 * 197 * <h5 class='section'>Notes:</h5><ul> 198 * <li class='note'> 199 * 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. 200 * <br>The leading and trailing <js>'['</js> and <js>']'</js> characters are optional. 201 * <li class='note'> 202 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 203 * <li> 204 * </ul> 205 * 206 * @return The annotation value. 207 */ 208 String[] parameters() default {}; 209 210 /** 211 * Defines the swagger field <c>/paths/{path}/{method}/produces</c>. 212 * 213 * <p> 214 * Use this value to override the supported <c>Accept</c> media types defined by the serializers defined via {@link RestOp#serializers()}. 215 * 216 * <h5 class='section'>Notes:</h5><ul> 217 * <li class='note'> 218 * 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. 219 * <li class='note'> 220 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 221 * <li class='note'> 222 * Values defined on this annotation override values defined for the method in the class swagger. 223 * </ul> 224 * 225 * @return The annotation value. 226 */ 227 String[] produces() default {}; 228 229 /** 230 * Defines the swagger field <c>/paths/{path}/{method}/responses</c>. 231 * 232 * <p> 233 * This annotation is provided for documentation purposes and is used to populate the method <js>"responses"</js> 234 * column on the Swagger page. 235 * 236 * <h5 class='section'>Example:</h5> 237 * <p class='bjava'> 238 * <ja>@RestGet</ja>( 239 * path=<js>"/"</js>, 240 * swagger=<ja>@OpSwagger</ja>( 241 * responses={ 242 * <js>"200:{ description:'Okay' },"</js>, 243 * <js>"302:{ description:'Thing wasn't found here', headers={Location:{description:'The place to find the thing.'}}}"</js> 244 * } 245 * ) 246 * ) 247 * </p> 248 * 249 * <h5 class='section'>Notes:</h5><ul> 250 * <li class='note'> 251 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object consisting of the concatenated individual strings. 252 * <br>The leading and trailing <js>'{'</js> and <js>'}'</js> characters are optional. 253 * <li class='note'> 254 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 255 * </ul> 256 * 257 * @return The annotation value. 258 */ 259 String[] responses() default {}; 260 261 /** 262 * Defines the swagger field <c>/paths/{path}/{method}/schemes</c>. 263 * 264 * <h5 class='section'>Notes:</h5><ul> 265 * <li class='note'> 266 * 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. 267 * <li class='note'> 268 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 269 * <li class='note'> 270 * Values defined on this annotation override values defined for the method in the class swagger. 271 * </ul> 272 * 273 * @return The annotation value. 274 */ 275 String[] schemes() default {}; 276 277 /** 278 * Defines the swagger field <c>/paths/{path}/{method}/summary</c>. 279 * 280 * <h5 class='section'>Notes:</h5><ul> 281 * <li class='note'> 282 * The format is plain text. 283 * <br>Multiple lines are concatenated with newlines. 284 * <li class='note'> 285 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 286 * <li class='note'> 287 * Values defined on this annotation override values defined for the method in the class swagger. 288 * <li class='note'> 289 * If not specified, the value is pulled from {@link RestOp#summary()}. 290 * </ul> 291 * 292 * @return The annotation value. 293 */ 294 String[] summary() default {}; 295 296 /** 297 * Optional tagging information for the exposed API. 298 * 299 * <p> 300 * Used to populate the Swagger tags field. 301 * 302 * <p> 303 * A comma-delimited list of tags for API documentation control. 304 * <br>Tags can be used for logical grouping of operations by resources or any other qualifier. 305 * 306 * <h5 class='section'>Example:</h5> 307 * <p class='bjava'> 308 * <ja>@RestGet</ja>( 309 * swagger=<ja>@OpSwagger</ja>( 310 * tags=<js>"foo,bar"</js> 311 * ) 312 * ) 313 * </p> 314 * 315 * <h5 class='section'>Notes:</h5><ul> 316 * <li class='note'> 317 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 318 * <li class='note'> 319 * Corresponds to the swagger field <c>/paths/{path}/{method}/tags</c>. 320 * </ul> 321 * 322 * @return The annotation value. 323 */ 324 String[] tags() default {}; 325 326 /** 327 * Free-form value for the swagger of a resource method. 328 * 329 * <p> 330 * 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. 331 * 332 * <p> 333 * The following are completely equivalent ways of defining the swagger description of a resource method: 334 * <p class='bjava'> 335 * <jc>// Normal</jc> 336 * <ja>@RestPost</ja>( 337 * path=<js>"/pet"</js>, 338 * swagger=<ja>@OpSwagger</ja>( 339 * summary=<js>"Add pet"</js>, 340 * description=<js>"Adds a new pet to the store"</js>, 341 * tags=<js>"pet"</js>, 342 * externalDocs=<ja>@ExternalDocs</ja>( 343 * description=<js>"Home page"</js>, 344 * url=<js>"http://juneau.apache.org"</js> 345 * ) 346 * ) 347 * ) 348 * </p> 349 * <p class='bjava'> 350 * <jc>// Free-form</jc> 351 * <ja>@RestPost</ja>( 352 * path=<js>"/pet"</js>, 353 * swagger=<ja>@OpSwagger</ja>({ 354 * <js>"summary: 'Add pet',"</js>, 355 * <js>"description: 'Adds a new pet to the store',"</js>, 356 * <js>"tags: ['pet'],"</js>, 357 * <js>"externalDocs:{"</js>, 358 * <js>"description: 'Home page',"</js>, 359 * <js>"url: 'http://juneau.apache.org'"</js>, 360 * <js>"}"</js> 361 * }) 362 * ) 363 * </p> 364 * <p class='bjava'> 365 * <jc>// Free-form with variables</jc> 366 * <ja>@RestPost</ja>( 367 * path=<js>"/pet"</js>, 368 * swagger=<ja>@OpSwagger</ja>(<js>"$L{addPetSwagger}"</js>) 369 * ) 370 * </p> 371 * <p class='bini'> 372 * <mc>// Contents of MyResource.properties</mc> 373 * <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> 374 * </p> 375 * 376 * <p> 377 * The reasons why you may want to use this field include: 378 * <ul> 379 * <li>You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file. 380 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 381 * </ul> 382 * 383 * <h5 class='section'>Notes:</h5><ul> 384 * <li class='note'> 385 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 386 * <li class='note'> 387 * The leading/trailing <c>{ }</c> characters are optional. 388 * <br>The following two example are considered equivalent: 389 * <p class='bjava'> 390 * <ja>@OpSwagger</ja>(<js>"{summary: 'Add pet'}"</js>) 391 * </p> 392 * <p class='bjava'> 393 * <ja>@OpSwagger</ja>(<js>"summary: 'Add pet'"</js>) 394 * </p> 395 * <li class='note'> 396 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 397 * <li class='note'> 398 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 399 * <li class='note'> 400 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 401 * </ul> 402 * 403 * @return The annotation value. 404 */ 405 String[] value() default {}; 406}