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.*; 020import org.apache.juneau.http.annotation.*; 021 022/** 023 * Extended annotation for {@link Rest#swagger() @Rest(swagger)}. 024 * 025 * <h5 class='section'>See Also:</h5><ul> 026 * <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a> 027 * </ul> 028 */ 029@Retention(RUNTIME) 030public @interface Swagger { 031 032 /** 033 * Defines the swagger field <c>/info/contact</c>. 034 * 035 * <p> 036 * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields: 037 * <p class='bschema'> 038 * { 039 * name: string, 040 * url: string, 041 * email: string 042 * } 043 * </p> 044 * 045 * <p> 046 * The default value pulls the description from the <c>contact</c> entry in the servlet resource bundle. 047 * (e.g. <js>"contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js> or 048 * <js>"MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}"</js>). 049 * 050 * <h5 class='section'>Example:</h5> 051 * <p class='bjava'> 052 * <ja>@Rest</ja>( 053 * swagger=<ja>@Swagger</ja>( 054 * contact=<js>"{name:'John Smith',email:'john.smith@foo.bar'}"</js> 055 * ) 056 * ) 057 * </p> 058 * 059 * <h5 class='section'>Notes:</h5><ul> 060 * <li class='note'> 061 * The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object. 062 * <br>Multiple lines are concatenated with newlines. 063 * <li class='note'> 064 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 065 * </ul> 066 * 067 * @return The annotation value. 068 */ 069 Contact contact() default @Contact; 070 071 /** 072 * Defines the swagger field <c>/info/description</c>. 073 * 074 * <h5 class='section'>Example:</h5> 075 * <p class='bjava'> 076 * <ja>@Rest</ja>( 077 * swagger=<ja>@Swagger</ja>( 078 * description={ 079 * <js>"This is a sample server Petstore server based on the Petstore sample at Swagger.io."</js>, 080 * <js>"You can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>."</js> 081 * } 082 * ) 083 * ) 084 * </p> 085 * 086 * <h5 class='section'>Notes:</h5><ul> 087 * <li class='note'> 088 * The format is plain text. 089 * <br>Multiple lines are concatenated with newlines. 090 * <li class='note'> 091 * The precedence of lookup for this field is: 092 * <ol> 093 * <li><c>{resource-class}.description</c> property in resource bundle. 094 * <li>{@link Swagger#description()} on this class, then any parent classes. 095 * <li>Value defined in Swagger JSON file. 096 * <li>{@link Rest#description()} on this class, then any parent classes. 097 * </ol> 098 * <li class='note'> 099 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 100 * </ul> 101 * 102 * @return The annotation value. 103 */ 104 String[] description() default {}; 105 106 /** 107 * Defines the swagger field <c>/externalDocs</c>. 108 * 109 * <p> 110 * It is used to populate the Swagger external documentation field and to display on HTML pages. 111 * * 112 * <p> 113 * The default value pulls the description from the <c>externalDocs</c> entry in the servlet resource bundle. 114 * (e.g. <js>"externalDocs = {url:'http://juneau.apache.org'}"</js> or 115 * <js>"MyServlet.externalDocs = {url:'http://juneau.apache.org'}"</js>). 116 * 117 * <h5 class='section'>Example:</h5> 118 * <p class='bjava'> 119 * <ja>@Rest</ja>( 120 * swagger=<ja>@Swagger</ja>( 121 * externalDocs=<ja>@ExternalDocs</ja>(url=<js>"http://juneau.apache.org"</js>) 122 * ) 123 * ) 124 * </p> 125 * 126 * @return The annotation value. 127 */ 128 ExternalDocs externalDocs() default @ExternalDocs; 129 130 /** 131 * Defines the swagger field <c>/info/license</c>. 132 * 133 * <p> 134 * It is used to populate the Swagger license field and to display on HTML pages. 135 * 136 * <p> 137 * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields: 138 * <p class='bschema'> 139 * { 140 * name: string, 141 * url: string 142 * } 143 * </p> 144 * 145 * <p> 146 * The default value pulls the description from the <c>license</c> entry in the servlet resource bundle. 147 * (e.g. <js>"license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> or 148 * <js>"MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js>). 149 * 150 * <h5 class='section'>Example:</h5> 151 * <p class='bjava'> 152 * <ja>@Rest</ja>( 153 * swagger=<ja>@Swagger</ja>( 154 * license=<js>"{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"</js> 155 * ) 156 * ) 157 * </p> 158 * 159 * <h5 class='section'>Notes:</h5><ul> 160 * <li class='note'> 161 * The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object. 162 * <br>Multiple lines are concatenated with newlines. 163 * <li class='note'> 164 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 165 * </ul> 166 * 167 * @return The annotation value. 168 */ 169 License license() default @License; 170 171 /** 172 * Defines the swagger field <c>/tags</c>. 173 * 174 * 175 * Optional tagging information for the exposed API. 176 * 177 * <p> 178 * It is used to populate the Swagger tags field and to display on HTML pages. 179 * 180 * <p> 181 * A <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> string with the following fields: 182 * <p class='bschema'> 183 * [ 184 * { 185 * name: string, 186 * description: string, 187 * externalDocs: { 188 * description: string, 189 * url: string 190 * } 191 * } 192 * ] 193 * </p> 194 * 195 * <p> 196 * The default value pulls the description from the <c>tags</c> entry in the servlet resource bundle. 197 * (e.g. <js>"tags = [{name:'Foo',description:'Foobar'}]"</js> or 198 * <js>"MyServlet.tags = [{name:'Foo',description:'Foobar'}]"</js>). 199 * 200 * <h5 class='section'>Example:</h5> 201 * <p class='bjava'> 202 * <ja>@Rest</ja>( 203 * swagger=<ja>@Swagger</ja>( 204 * tags=<js>"[{name:'Foo',description:'Foobar'}]"</js> 205 * ) 206 * ) 207 * </p> 208 * 209 * <h5 class='section'>Notes:</h5><ul> 210 * <li class='note'> 211 * The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> array. 212 * <br>Multiple lines are concatenated with newlines. 213 * <li class='note'> 214 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 215 * </ul> 216 * 217 * @return The annotation value. 218 */ 219 Tag[] tags() default {}; 220 221 /** 222 * Defines the swagger field <c>/info/termsOfService</c>. 223 * 224 * 225 * Optional servlet terms-of-service for this API. 226 * 227 * <p> 228 * It is used to populate the Swagger terms-of-service field. 229 * 230 * <p> 231 * The default value pulls the description from the <c>termsOfService</c> entry in the servlet resource bundle. 232 * (e.g. <js>"termsOfService = foo"</js> or <js>"MyServlet.termsOfService = foo"</js>). 233 * 234 * <h5 class='section'>Notes:</h5><ul> 235 * <li class='note'> 236 * The format is plain text. 237 * <br>Multiple lines are concatenated with newlines. 238 * <li class='note'> 239 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 240 * </ul> 241 * 242 * @return The annotation value. 243 */ 244 String[] termsOfService() default {}; 245 246 /** 247 * Defines the swagger field <c>/info/title</c>. 248 * 249 * <h5 class='section'>Example:</h5> 250 * <p class='bjava'> 251 * <ja>@Rest</ja>( 252 * swagger=<ja>@Swagger</ja>( 253 * title=<js>"Petstore application"</js> 254 * ) 255 * ) 256 * </p> 257 * 258 * <h5 class='section'>Notes:</h5><ul> 259 * <li class='note'> 260 * The format is plain-text. 261 * <br>Multiple lines are concatenated with newlines. 262 * <li class='note'> 263 * The precedence of lookup for this field is: 264 * <ol> 265 * <li><c>{resource-class}.title</c> property in resource bundle. 266 * <li>{@link Swagger#title()} on this class, then any parent classes. 267 * <li>Value defined in Swagger JSON file. 268 * <li>{@link Rest#title()} on this class, then any parent classes. 269 * </ol> 270 * <li class='note'> 271 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 272 * </ul> 273 * 274 * @return The annotation value. 275 */ 276 String[] title() default {}; 277 278 /** 279 * Free-form value for the swagger of a resource. 280 * 281 * <p> 282 * This is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object that makes up the swagger information for this resource. 283 * 284 * <p> 285 * The following are completely equivalent ways of defining the swagger description of a resource: 286 * <p class='bjava'> 287 * <jc>// Normal</jc> 288 * <ja>@Rest</ja>( 289 * swagger=<ja>@Swagger</ja>( 290 * title=<js>"Petstore application"</js>, 291 * description={ 292 * <js>"This is a sample server Petstore server based on the Petstore sample at Swagger.io."</js>, 293 * <js>"You can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>."</js> 294 * }, 295 * contact=<ja>@Contact</ja>( 296 * name=<js>"John Smith"</js>, 297 * email=<js>"john@smith.com"</js> 298 * ), 299 * license=<ja>@License</ja>( 300 * name=<js>"Apache 2.0"</js>, 301 * url=<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js> 302 * ), 303 * version=<js>"2.0"</js>, 304 * termsOfService=<js>"You are on your own."</js>, 305 * tags={ 306 * <ja>@Tag</ja>( 307 * name=<js>"Java"</js>, 308 * description=<js>"Java utility"</js>, 309 * externalDocs=<ja>@ExternalDocs</ja>( 310 * description=<js>"Home page"</js>, 311 * url=<js>"http://juneau.apache.org"</js> 312 * ) 313 * } 314 * }, 315 * externalDocs=<ja>@ExternalDocs</ja>( 316 * description=<js>"Home page"</js>, 317 * url=<js>"http://juneau.apache.org"</js> 318 * ) 319 * ) 320 * ) 321 * </p> 322 * <p class='bjava'> 323 * <jc>// Free-form</jc> 324 * <ja>@Rest</ja>( 325 * swagger=@Swagger({ 326 * <js>"title: 'Petstore application',"</js>, 327 * <js>"description: 'This is a sample server Petstore server based on the Petstore sample at Swagger.io.\nYou can find out more about Swagger at <a class='link' href='http://swagger.io'>http://swagger.io</a>.',"</js>, 328 * <js>"contact:{"</js>, 329 * <js>"name: 'John Smith',"</js>, 330 * <js>"email: 'john@smith.com'"</js>, 331 * <js>"},"</js>, 332 * <js>"license:{"</js>, 333 * <js>"name: 'Apache 2.0',"</js>, 334 * <js>"url: 'http://www.apache.org/licenses/LICENSE-2.0.html'"</js>, 335 * <js>"},"</js>, 336 * <js>"version: '2.0',"</js>, 337 * <js>"termsOfService: 'You are on your own.',"</js>, 338 * <js>"tags:["</js>, 339 * <js>"{"</js>, 340 * <js>"name: 'Java',"</js>, 341 * <js>"description: 'Java utility',"</js>, 342 * <js>"externalDocs:{"</js>, 343 * <js>"description: 'Home page',"</js>, 344 * <js>"url: 'http://juneau.apache.org'"</js>, 345 * <js>"}"</js>, 346 * <js>"}"</js>, 347 * <js>"],"</js>, 348 * <js>"externalDocs:{"</js>, 349 * <js>"description: 'Home page',"</js>, 350 * <js>"url: 'http://juneau.apache.org'"</js>, 351 * <js>"}"</js> 352 * }) 353 * ) 354 * </p> 355 * <p class='bjava'> 356 * <jc>// Free-form with variables</jc> 357 * <ja>@Rest</ja>( 358 * swagger=@Swagger(<js>"$F{MyResourceSwagger.json}"</js>) 359 * ) 360 * </p> 361 * 362 * <p> 363 * The reasons why you may want to use this field include: 364 * <ul> 365 * <li>You want to pull in the entire Swagger JSON definition for this content from an external source such as a properties file. 366 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 367 * </ul> 368 * 369 * <h5 class='section'>Notes:</h5><ul> 370 * <li class='note'> 371 * The format is a <a class="doclink" href="../../../../../index.html#jd.Swagger">Swagger</a> object. 372 * <li class='note'> 373 * The leading/trailing <c>{ }</c> characters are optional. 374 * <br>The following two example are considered equivalent: 375 * <p class='bjava'> 376 * <ja>@Swagger</ja>(<js>"{title:'Petstore application'}"</js>) 377 * </p> 378 * <p class='bjava'> 379 * <ja>@Swagger</ja>(<js>"title:'Petstore application'"</js>) 380 * </p> 381 * <li class='note'> 382 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 383 * <li class='note'> 384 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 385 * <li class='note'> 386 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 387 * </ul> 388 * 389 * @return The annotation value. 390 */ 391 String[] value() default {}; 392 393 /** 394 * Defines the swagger field <c>/info/version</c>. 395 * 396 * 397 * 398 * Provides the version of the application API (not to be confused with the specification version). 399 * 400 * <p> 401 * It is used to populate the Swagger version field and to display on HTML pages. 402 * 403 * <p> 404 * The default value pulls the description from the <c>version</c> entry in the servlet resource bundle. 405 * (e.g. <js>"version = 2.0"</js> or <js>"MyServlet.version = 2.0"</js>). 406 * 407 * <h5 class='section'>Notes:</h5><ul> 408 * <li class='note'> 409 * The format is plain text. 410 * <li class='note'> 411 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>). 412 * </ul> 413 * 414 * @return The annotation value. 415 */ 416 String version() default ""; 417}