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.internal.BeanPropertyUtils.*;
016
017import java.net.*;
018import java.net.URI;
019
020import org.apache.juneau.*;
021import org.apache.juneau.annotation.*;
022
023/**
024 * Allows referencing an external resource for extended documentation.
025 * 
026 * <h5 class='section'>Example:</h5>
027 * <p class='bcode'>
028 *    <jc>// Construct using SwaggerBuilder.</jc>
029 *    ExternalDocumentation x = <jsm>externalDocumentation</jsm>(<js>"https://swagger.io"</js>, <js>"Find more info here"</js>);
030 * 
031 *    <jc>// Serialize using JsonSerializer.</jc>
032 *    String json = JsonSerializer.<jsf>DEFAULT</jsf>.toString(x);
033 * 
034 *    <jc>// Or just use toString() which does the same as above.</jc>
035 *    String json = x.toString();
036 * </p>
037 * <p class='bcode'>
038 *    <jc>// Output</jc>
039 *    {
040 *       <js>"description"</js>: <js>"Find more info here"</js>,
041 *       <js>"url"</js>: <js>"https://swagger.io"</js>
042 *    }
043 * </p>
044 * 
045 * <h5 class='section'>See Also:</h5>
046 * <ul class='doctree'>
047 *    <li class='link'><a class='doclink' href='../../../../../overview-summary.html#juneau-dto.Swagger'>Overview &gt; juneau-dto &gt; Swagger</a>
048 * </ul>
049 */
050@Bean(properties="description,url,*")
051public class ExternalDocumentation extends SwaggerElement {
052
053   private String description;
054   private URI url;
055
056   /**
057    * Bean property getter:  <property>description</property>.
058    * 
059    * <p>
060    * A short description of the target documentation. 
061    * 
062    * @return The property value, or <jk>null</jk> if it is not set.
063    */
064   public String getDescription() {
065      return description;
066   }
067
068   /**
069    * Bean property setter:  <property>description</property>.
070    * 
071    * <p>
072    * A short description of the target documentation. 
073    * 
074    * @param value 
075    *    The new value for this property.
076    *    <br><a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used for rich text representation.
077    *    <br>Can be <jk>null</jk> to unset the property.
078    * @return This object (for method chaining).
079    */
080   public ExternalDocumentation setDescription(String value) {
081      description = value;
082      return this;
083   }
084
085   /**
086    * Same as {@link #setDescription(String)}.
087    * 
088    * @param value
089    *    The new value for this property.
090    *    <br>Non-String values will be converted to String using <code>toString()</code>.
091    *    <br>Can be <jk>null</jk> to unset the property.
092    * @return This object (for method chaining).
093    */
094   public ExternalDocumentation description(Object value) {
095      return setDescription(toStringVal(value));
096   }
097
098   /**
099    * Bean property getter:  <property>url</property>.
100    * 
101    * <p>
102    * The URL for the target documentation.
103    * 
104    * @return The property value, or <jk>null</jk> if it is not set.
105    */
106   public URI getUrl() {
107      return url;
108   }
109
110   /**
111    * Bean property setter:  <property>url</property>.
112    * 
113    * <p>
114    * The URL for the target documentation.
115    * 
116    * @param value 
117    *    The new value for this property.
118    *    <br>Property value is required.
119    *    <br>URIs defined by {@link UriResolver} can be used for values.
120    * @return This object (for method chaining).
121    */
122   public ExternalDocumentation setUrl(URI value) {
123      url = value;
124      return this;
125   }
126
127   /**
128    * Same as {@link #setUrl(URI)}.
129    * 
130    * @param value
131    *    The new value for this property.
132    *    <br>URIs defined by {@link UriResolver} can be used for values.
133    *    <br>Valid types:
134    *    <ul>
135    *       <li>{@link URI}
136    *       <li>{@link URL}
137    *       <li>{@link String} 
138    *          <br>Converted to URI using <code><jk>new</jk> URI(value.toString())</code>.
139    *       <li>
140    *    </ul>
141    *    <br>Can be <jk>null</jk> to unset the property.
142    * @return This object (for method chaining).
143    */
144   public ExternalDocumentation url(Object value) {
145      return setUrl(toURI(value));
146   }
147
148   @Override /* SwaggerElement */
149   public <T> T get(String property, Class<T> type) {
150      if (property == null)
151         return null;
152      switch (property) {
153         case "description": return toType(getDescription(), type);
154         case "url": return toType(getUrl(), type);
155         default: return super.get(property, type);
156      }
157   }
158
159   @Override /* SwaggerElement */
160   public ExternalDocumentation set(String property, Object value) {
161      if (property == null)
162         return this;
163      switch (property) {
164         case "description": return description(value);
165         case "url": return url(value);
166         default: 
167            super.set(property, value);
168            return this;
169      }
170   }
171}