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 &gt; juneau-rest-server &gt; 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}