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