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.annotation.*; 020 021/** 022 * Swagger tag annotation. 023 * 024 * <p> 025 * Allows adding meta data to a single tag that is used by the <a class="doclink" href="https://swagger.io/specification/v2#operationObject">Swagger Operation Object</a>. 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>@Rest</ja>-annotated classes. 030 * 031 * <h5 class='section'>Example:</h5> 032 * <p class='bjava'> 033 * <jc>// A response object thats a hex-encoded string</jc> 034 * <ja>@Rest</ja>( 035 * swagger=<ja>@Swagger</ja>{ 036 * tags={ 037 * <ja>@Tag</ja>( 038 * name=<js>"utility"</js>, 039 * description=<js>"Utility methods"</js> 040 * ) 041 * } 042 * } 043 * ) 044 * </p> 045 * 046 * <h5 class='section'>See Also:</h5><ul> 047 * <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a> 048 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#tagObject">Swagger Tag Object</a> 049 050 * </ul> 051 */ 052@Documented 053@Retention(RUNTIME) 054public @interface Tag { 055 056 /** 057 * <mk>description</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#tagObject">Swagger Tag Object</a>. 058 * 059 * <h5 class='section'>Notes:</h5><ul> 060 * <li class='note'> 061 * The format is a <a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a> object. 062 * <br>Multiple lines are concatenated with newlines. 063 * <li class='note'> 064 * Supports <a class="doclink" href="../../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator. 065 * </ul> 066 * 067 * @return The annotation value. 068 */ 069 String[] description() default {}; 070 071 /** 072 * <mk>externalDocs</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#tagObject">Swagger Tag Object</a>. 073 * 074 * <h5 class='section'>Notes:</h5><ul> 075 * <li class='note'> 076 * The format is a <a class="doclink" href="../../../../../index.html#jrs.Swagger">Swagger</a> object. 077 * <br>Multiple lines are concatenated with newlines. 078 * </ul> 079 * 080 * @return The annotation value. 081 */ 082 ExternalDocs externalDocs() default @ExternalDocs; 083 084 /** 085 * <mk>name</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#tagObject">Swagger Tag Object</a>. 086 * 087 * <h5 class='section'>Notes:</h5><ul> 088 * <li class='note'> 089 * The format is plain text. 090 * </ul> 091 * 092 * @return The annotation value. 093 */ 094 String name() default ""; 095}