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