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