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.http.annotation; 014 015import static java.lang.annotation.RetentionPolicy.*; 016 017import java.lang.annotation.*; 018 019import org.apache.juneau.jsonschema.annotation.ExternalDocs; 020 021/** 022 * Swagger tag annotation. 023 * 024 * <p> 025 * Allows adding meta data to a single tag that is used by the {@doc SwaggerOperationObject}. 026 * It is not mandatory to have a Tag Object per tag used there. 027 * 028 * <p> 029 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes. 030 * 031 * <h5 class='section'>Examples:</h5> 032 * <p class='bcode w800'> 033 * <jc>// A response object thats a hex-encoded string</jc> 034 * <ja>@RestResource</ja>( 035 * swagger={ 036 * tags={ 037 * <ja>@Tag</ja>( 038 * name=<js>"utility"</js>, 039 * description=<js>"Utility methods"</js> 040 * ) 041 * } 042 * } 043 * ) 044 * </p> 045 * <p class='bcode w800'> 046 * <jc>// Free-form</jc> 047 * <ja>@RestResource</ja>( 048 * swagger={ 049 * tags={ 050 * <ja>@Tag</ja>({ 051 * <js>"name:'utility',"</js>, 052 * <js>"description:'Utility methods'"</js> 053 * }) 054 * } 055 * } 056 * ) 057 * </p> 058 * 059 * <ul class='seealso'> 060 * <li class='link'>{@doc juneau-rest-server.Swagger} 061 * <li class='extlink'>{@doc SwaggerTagObject} 062 * </ul> 063 */ 064@Documented 065@Retention(RUNTIME) 066public @interface Tag { 067 068 /** 069 * <mk>name</mk> field of the {@doc SwaggerTagObject}. 070 * 071 * <ul class='notes'> 072 * <li> 073 * The format is plain text. 074 * </ul> 075 */ 076 String name() default ""; 077 078 /** 079 * <mk>description</mk> field of the {@doc SwaggerTagObject}. 080 * 081 * <ul class='notes'> 082 * <li> 083 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 084 * <br>Multiple lines are concatenated with newlines. 085 * <li> 086 * Supports {@doc DefaultRestSvlVariables} 087 * (e.g. <js>"$L{my.localized.variable}"</js>). 088 * </ul> 089 */ 090 String[] description() default {}; 091 092 /** 093 * <mk>externalDocs</mk> field of the {@doc SwaggerTagObject}. 094 * 095 * <ul class='notes'> 096 * <li> 097 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 098 * <br>Multiple lines are concatenated with newlines. 099 * <li> 100 * Supports {@doc DefaultRestSvlVariables} 101 * (e.g. <js>"$L{my.localized.variable}"</js>). 102 * </ul> 103 */ 104 ExternalDocs externalDocs() default @ExternalDocs; 105 106 /** 107 * Free-form value for the {@doc SwaggerTagObject}. 108 * 109 * <p> 110 * This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this Tag object. 111 * 112 * <p> 113 * The following are completely equivalent ways of defining the swagger description of the resource tags: 114 * <p class='bcode w800'> 115 * <jc>// Normal</jc> 116 * <ja>@RestResource</ja>( 117 * tags={ 118 * <ja>@Tag</ja>( 119 * name=<js>"pet"</js>, 120 * description=<js>"Everything about your Pets"</js>, 121 * externalDocs=<ja>@ExternalDocs</ja>( 122 * description="<js>Find out more"</js>, 123 * url=<js>"http://juneau.apache.org"</js> 124 * } 125 * ) 126 * } 127 * ) 128 * </p> 129 * <p class='bcode w800'> 130 * <jc>// Free-form</jc> 131 * <ja>@RestResource</ja>( 132 * tags={ 133 * <ja>@Tag</ja>( 134 * name=<js>"pet"</js>, 135 * api={ 136 * <js>"name: 'pet',"</js>, 137 * <js>"description: 'Everything about your Pets',"</js>, 138 * <js>"externalDocs: {"</js>, 139 * <js>"description: 'Find out more',"</js>, 140 * <js>"url: 'http://juneau.apache.org'"</js> 141 * <js>"}"</js> 142 * } 143 * ) 144 * } 145 * ) 146 * </p> 147 * <p class='bcode w800'> 148 * <jc>// Free-form with variables</jc> 149 * <ja>@RestResource</ja>( 150 * tags={ 151 * <ja>@Tag</ja>( 152 * name=<js>"pet"</js>, 153 * api=<js>"$L{petTagSwagger}"</js> 154 * ) 155 * } 156 * ) 157 * </p> 158 * <p class='bcode w800'> 159 * <mc>// Contents of MyResource.properties</mc> 160 * <mk>petTagSwagger</mk> = <mv>{ name: "pet", description: "Everything about your Pets", externalDocs: { description: "Find out more", url: "http://juneau.apache.org" } }</mv> 161 * </p> 162 * 163 * <p> 164 * The reasons why you may want to use this field include: 165 * <ul> 166 * <li>You want to pull in the entire Swagger JSON definition for this body from an external source such as a properties file. 167 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 168 * </ul> 169 * 170 * <ul class='notes'> 171 * <li> 172 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 173 * <li> 174 * The leading/trailing <c>{ }</c> characters are optional. 175 * <br>The following two example are considered equivalent: 176 * <p class='bcode w800'> 177 * <ja>@Tag</ja>(api=<js>"{description: 'Everything about your Pets'}"</js>) 178 * </p> 179 * <p class='bcode w800'> 180 * <ja>@Tag</ja>(api=<js>"description: 'Everything about your Pets'"</js>) 181 * </p> 182 * <li> 183 * Multiple lines are concatenated with newlines so that you can format the value to be readable: 184 * <li> 185 * Supports {@doc DefaultRestSvlVariables} 186 * (e.g. <js>"$L{my.localized.variable}"</js>). 187 * <li> 188 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 189 * </ul> 190 */ 191 String[] value() default {}; 192}