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