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