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.dto.swagger; 014 015import static org.apache.juneau.common.internal.StringUtils.*; 016import static org.apache.juneau.internal.CollectionUtils.*; 017import static org.apache.juneau.internal.ConverterUtils.*; 018 019import java.util.*; 020 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.internal.*; 023 024/** 025 * Allows adding meta data to a single tag that is used by the <a class="doclink" href="https://swagger.io/specification/v2#operationObject">Operation Object</a>. 026 * 027 * <p> 028 * It is not mandatory to have a Tag Object per tag used there. 029 * 030 * <h5 class='section'>Example:</h5> 031 * <p class='bjava'> 032 * <jc>// Construct using SwaggerBuilder.</jc> 033 * Tag <jv>tag</jv> = <jsm>tag</jsm>() 034 * .name(<js>"pet"</js>) 035 * .description(<js>"Pets operations"</js>) 036 * 037 * <jc>// Serialize using JsonSerializer.</jc> 038 * String <jv>json</jv> = JsonSerializer.<jsf>DEFAULT</jsf>.toString(<jv>tag</jv>); 039 * 040 * <jc>// Or just use toString() which does the same as above.</jc> 041 * <jv>json</jv> = <jv>tag</jv>.toString(); 042 * </p> 043 * <p class='bjson'> 044 * <jc>// Output</jc> 045 * { 046 * <js>"name"</js>: <js>"pet"</js>, 047 * <js>"description"</js>: <js>"Pets operations"</js> 048 * } 049 * </p> 050 * 051 * <h5 class='section'>See Also:</h5><ul> 052 * <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Overview > juneau-rest-server > Swagger</a> 053 * </ul> 054 */ 055@Bean(properties="name,description,externalDocs,*") 056@FluentSetters 057public class Tag extends SwaggerElement { 058 059 private String 060 name, 061 description; 062 private ExternalDocumentation externalDocs; 063 064 /** 065 * Default constructor. 066 */ 067 public Tag() {} 068 069 /** 070 * Copy constructor. 071 * 072 * @param copyFrom The object to copy. 073 */ 074 public Tag(Tag copyFrom) { 075 super(copyFrom); 076 077 this.description = copyFrom.description; 078 this.externalDocs = copyFrom.externalDocs == null ? null : copyFrom.externalDocs.copy(); 079 this.name = copyFrom.name; 080 } 081 082 /** 083 * Make a deep copy of this object. 084 * 085 * @return A deep copy of this object. 086 */ 087 public Tag copy() { 088 return new Tag(this); 089 } 090 091 //----------------------------------------------------------------------------------------------------------------- 092 // Properties 093 //----------------------------------------------------------------------------------------------------------------- 094 095 /** 096 * Bean property getter: <property>description</property>. 097 * 098 * <p> 099 * A short description for the tag. 100 * 101 * @return The property value, or <jk>null</jk> if it is not set. 102 */ 103 public String getDescription() { 104 return description; 105 } 106 107 /** 108 * Bean property setter: <property>description</property>. 109 * 110 * <p> 111 * A short description for the tag. 112 * 113 * @param value 114 * The new value for this property. 115 * <br><a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used for rich text representation. 116 * <br>Can be <jk>null</jk> to unset the property. 117 * @return This object. 118 */ 119 public Tag setDescription(String value) { 120 description = value; 121 return this; 122 } 123 124 /** 125 * Bean property getter: <property>externalDocs</property>. 126 * 127 * <p> 128 * Additional external documentation for this tag. 129 * 130 * @return The property value, or <jk>null</jk> if it is not set. 131 */ 132 public ExternalDocumentation getExternalDocs() { 133 return externalDocs; 134 } 135 136 /** 137 * Bean property setter: <property>externalDocs</property>. 138 * 139 * <p> 140 * Additional external documentation for this tag. 141 * 142 * @param value 143 * The new value for this property. 144 * <br>Can be <jk>null</jk> to unset the property. 145 * @return This object. 146 */ 147 public Tag setExternalDocs(ExternalDocumentation value) { 148 externalDocs = value; 149 return this; 150 } 151 152 /** 153 * Bean property getter: <property>name</property>. 154 * 155 * <p> 156 * The name of the tag. 157 * 158 * @return The property value, or <jk>null</jk> if it is not set. 159 */ 160 public String getName() { 161 return name; 162 } 163 164 /** 165 * Bean property setter: <property>name</property>. 166 * 167 * <p> 168 * The name of the tag. 169 * 170 * @param value 171 * The new value for this property. 172 * <br>Property value is required. 173 * @return This object. 174 */ 175 public Tag setName(String value) { 176 name = value; 177 return this; 178 } 179 180 // <FluentSetters> 181 182 // </FluentSetters> 183 184 @Override /* SwaggerElement */ 185 public <T> T get(String property, Class<T> type) { 186 if (property == null) 187 return null; 188 switch (property) { 189 case "description": return toType(getDescription(), type); 190 case "externalDocs": return toType(getExternalDocs(), type); 191 case "name": return toType(getName(), type); 192 default: return super.get(property, type); 193 } 194 } 195 196 @Override /* SwaggerElement */ 197 public Tag set(String property, Object value) { 198 if (property == null) 199 return this; 200 switch (property) { 201 case "description": return setDescription(stringify(value)); 202 case "externalDocs": return setExternalDocs(toType(value, ExternalDocumentation.class)); 203 case "name": return setName(stringify(value)); 204 default: 205 super.set(property, value); 206 return this; 207 } 208 } 209 210 @Override /* SwaggerElement */ 211 public Set<String> keySet() { 212 Set<String> s = setBuilder(String.class) 213 .addIf(description != null, "description") 214 .addIf(externalDocs != null, "externalDocs") 215 .addIf(name != null, "name") 216 .build(); 217 return new MultiSet<>(s, super.keySet()); 218 } 219}