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 * <h5 class='section'>See Also:</h5> 060 * <ul> 061 * <li class='link'>{@doc juneau-rest-server.Swagger} 062 * <li class='extlink'>{@doc SwaggerTagObject} 063 * </ul> 064 */ 065@Documented 066@Retention(RUNTIME) 067public @interface Tag { 068 069 /** 070 * <mk>name</mk> field of the {@doc SwaggerTagObject}. 071 * 072 * <h5 class='section'>Notes:</h5> 073 * <ul class='spaced-list'> 074 * <li> 075 * The format is plain text. 076 * </ul> 077 */ 078 String name() default ""; 079 080 /** 081 * <mk>description</mk> field of the {@doc SwaggerTagObject}. 082 * 083 * <h5 class='section'>Notes:</h5> 084 * <ul class='spaced-list'> 085 * <li> 086 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 087 * <br>Multiple lines are concatenated with newlines. 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 * <mk>externalDocs</mk> field of the {@doc SwaggerTagObject}. 097 * 098 * <h5 class='section'>Notes:</h5> 099 * <ul class='spaced-list'> 100 * <li> 101 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 102 * <br>Multiple lines are concatenated with newlines. 103 * <li> 104 * Supports {@doc DefaultRestSvlVariables} 105 * (e.g. <js>"$L{my.localized.variable}"</js>). 106 * </ul> 107 */ 108 ExternalDocs externalDocs() default @ExternalDocs; 109 110 /** 111 * Free-form value for the {@doc SwaggerTagObject}. 112 * 113 * <p> 114 * This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this Tag object. 115 * 116 * <p> 117 * The following are completely equivalent ways of defining the swagger description of the resource tags: 118 * <p class='bcode w800'> 119 * <jc>// Normal</jc> 120 * <ja>@RestResource</ja>( 121 * tags={ 122 * <ja>@Tag</ja>( 123 * name=<js>"pet"</js>, 124 * description=<js>"Everything about your Pets"</js>, 125 * externalDocs=<ja>@ExternalDocs</ja>( 126 * description="<js>Find out more"</js>, 127 * url=<js>"http://juneau.apache.org"</js> 128 * } 129 * ) 130 * } 131 * ) 132 * </p> 133 * <p class='bcode w800'> 134 * <jc>// Free-form</jc> 135 * <ja>@RestResource</ja>( 136 * tags={ 137 * <ja>@Tag</ja>( 138 * name=<js>"pet"</js>, 139 * api={ 140 * <js>"name: 'pet',"</js>, 141 * <js>"description: 'Everything about your Pets',"</js>, 142 * <js>"externalDocs: {"</js>, 143 * <js>"description: 'Find out more',"</js>, 144 * <js>"url: 'http://juneau.apache.org'"</js> 145 * <js>"}"</js> 146 * } 147 * ) 148 * } 149 * ) 150 * </p> 151 * <p class='bcode w800'> 152 * <jc>// Free-form with variables</jc> 153 * <ja>@RestResource</ja>( 154 * tags={ 155 * <ja>@Tag</ja>( 156 * name=<js>"pet"</js>, 157 * api=<js>"$L{petTagSwagger}"</js> 158 * ) 159 * } 160 * ) 161 * </p> 162 * <p class='bcode w800'> 163 * <mc>// Contents of MyResource.properties</mc> 164 * <mk>petTagSwagger</mk> = <mv>{ name: "pet", description: "Everything about your Pets", externalDocs: { description: "Find out more", url: "http://juneau.apache.org" } }</mv> 165 * </p> 166 * 167 * <p> 168 * The reasons why you may want to use this field include: 169 * <ul> 170 * <li>You want to pull in the entire Swagger JSON definition for this body from an external source such as a properties file. 171 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 172 * </ul> 173 * 174 * <h5 class='section'>Notes:</h5> 175 * <ul class='spaced-list'> 176 * <li> 177 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 178 * <li> 179 * The leading/trailing <code>{ }</code> characters are optional. 180 * <br>The following two example are considered equivalent: 181 * <p class='bcode w800'> 182 * <ja>@Tag</ja>(api=<js>"{description: 'Everything about your Pets'}"</js>) 183 * </p> 184 * <p class='bcode w800'> 185 * <ja>@Tag</ja>(api=<js>"description: 'Everything about your Pets'"</js>) 186 * </p> 187 * <li> 188 * Multiple lines are concatenated with newlines so that you can format the value to be readable: 189 * <li> 190 * Supports {@doc DefaultRestSvlVariables} 191 * (e.g. <js>"$L{my.localized.variable}"</js>). 192 * <li> 193 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 194 * </ul> 195 */ 196 String[] value() default {}; 197}