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