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.*; 016import static org.apache.juneau.internal.StringUtils.*; 017 018import java.net.*; 019import java.net.URI; 020import java.util.*; 021 022import org.apache.juneau.*; 023import org.apache.juneau.annotation.*; 024import org.apache.juneau.internal.*; 025import org.apache.juneau.utils.*; 026 027/** 028 * Allows referencing an external resource for extended documentation. 029 * 030 * <h5 class='section'>Example:</h5> 031 * <p class='bcode w800'> 032 * <jc>// Construct using SwaggerBuilder.</jc> 033 * ExternalDocumentation x = <jsm>externalDocumentation</jsm>(<js>"https://swagger.io"</js>, <js>"Find more info here"</js>); 034 * 035 * <jc>// Serialize using JsonSerializer.</jc> 036 * String json = JsonSerializer.<jsf>DEFAULT</jsf>.toString(x); 037 * 038 * <jc>// Or just use toString() which does the same as above.</jc> 039 * String json = x.toString(); 040 * </p> 041 * <p class='bcode w800'> 042 * <jc>// Output</jc> 043 * { 044 * <js>"description"</js>: <js>"Find more info here"</js>, 045 * <js>"url"</js>: <js>"https://swagger.io"</js> 046 * } 047 * </p> 048 * 049 * <h5 class='section'>See Also:</h5> 050 * <ul class='doctree'> 051 * <li class='link'>{@doc juneau-dto.Swagger} 052 * </ul> 053 */ 054@Bean(properties="description,url,*") 055public class ExternalDocumentation extends SwaggerElement { 056 057 private String description; 058 private URI url; 059 060 /** 061 * Default constructor. 062 */ 063 public ExternalDocumentation() {} 064 065 /** 066 * Copy constructor. 067 * 068 * @param copyFrom The object to copy. 069 */ 070 public ExternalDocumentation(ExternalDocumentation copyFrom) { 071 super(copyFrom); 072 073 this.description = copyFrom.description; 074 this.url = copyFrom.url; 075 } 076 077 /** 078 * Make a deep copy of this object. 079 * 080 * @return A deep copy of this object. 081 */ 082 public ExternalDocumentation copy() { 083 return new ExternalDocumentation(this); 084 } 085 086 /** 087 * Bean property getter: <property>description</property>. 088 * 089 * <p> 090 * A short description of the target documentation. 091 * 092 * @return The property value, or <jk>null</jk> if it is not set. 093 */ 094 public String getDescription() { 095 return description; 096 } 097 098 /** 099 * Bean property setter: <property>description</property>. 100 * 101 * <p> 102 * A short description of the target documentation. 103 * 104 * @param value 105 * The new value for this property. 106 * <br>{@doc GFM} can be used for rich text representation. 107 * <br>Can be <jk>null</jk> to unset the property. 108 * @return This object (for method chaining). 109 */ 110 public ExternalDocumentation setDescription(String value) { 111 description = value; 112 return this; 113 } 114 115 /** 116 * Same as {@link #setDescription(String)}. 117 * 118 * @param value 119 * The new value for this property. 120 * <br>Non-String values will be converted to String using <code>toString()</code>. 121 * <br>Can be <jk>null</jk> to unset the property. 122 * @return This object (for method chaining). 123 */ 124 public ExternalDocumentation description(Object value) { 125 return setDescription(toStringVal(value)); 126 } 127 128 /** 129 * Bean property getter: <property>url</property>. 130 * 131 * <p> 132 * The URL for the target documentation. 133 * 134 * @return The property value, or <jk>null</jk> if it is not set. 135 */ 136 public URI getUrl() { 137 return url; 138 } 139 140 /** 141 * Bean property setter: <property>url</property>. 142 * 143 * <p> 144 * The URL for the target documentation. 145 * 146 * @param value 147 * The new value for this property. 148 * <br>Property value is required. 149 * <br>URIs defined by {@link UriResolver} can be used for values. 150 * @return This object (for method chaining). 151 */ 152 public ExternalDocumentation setUrl(URI value) { 153 url = value; 154 return this; 155 } 156 157 /** 158 * Same as {@link #setUrl(URI)}. 159 * 160 * @param value 161 * The new value for this property. 162 * <br>URIs defined by {@link UriResolver} can be used for values. 163 * <br>Valid types: 164 * <ul> 165 * <li>{@link URI} 166 * <li>{@link URL} 167 * <li>{@link String} 168 * <br>Converted to URI using <code><jk>new</jk> URI(value.toString())</code>. 169 * <li> 170 * </ul> 171 * <br>Can be <jk>null</jk> to unset the property. 172 * @return This object (for method chaining). 173 */ 174 public ExternalDocumentation url(Object value) { 175 return setUrl(StringUtils.toURI(value)); 176 } 177 178 /** 179 * Returns <jk>true</jk> if the url property is not null. 180 * 181 * @return <jk>true</jk> if the url property is not null. 182 */ 183 public boolean hasUrl() { 184 return url != null; 185 } 186 187 /** 188 * Returns <jk>true</jk> if the description property is not null or empty. 189 * 190 * @return <jk>true</jk> if the description property is not null or empty. 191 */ 192 public boolean hasDescription() { 193 return isNotEmpty(description); 194 } 195 196 @Override /* SwaggerElement */ 197 public <T> T get(String property, Class<T> type) { 198 if (property == null) 199 return null; 200 switch (property) { 201 case "description": return toType(getDescription(), type); 202 case "url": return toType(getUrl(), type); 203 default: return super.get(property, type); 204 } 205 } 206 207 @Override /* SwaggerElement */ 208 public ExternalDocumentation set(String property, Object value) { 209 if (property == null) 210 return this; 211 switch (property) { 212 case "description": return description(value); 213 case "url": return url(value); 214 default: 215 super.set(property, value); 216 return this; 217 } 218 } 219 220 @Override /* SwaggerElement */ 221 public Set<String> keySet() { 222 ASet<String> s = new ASet<String>() 223 .appendIf(description != null, "description") 224 .appendIf(url != null, "url"); 225 return new MultiSet<>(s, super.keySet()); 226 } 227}