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.net.*; 020import java.util.*; 021 022import org.apache.juneau.*; 023import org.apache.juneau.annotation.*; 024import org.apache.juneau.common.internal.*; 025import org.apache.juneau.internal.*; 026 027/** 028 * Allows referencing an external resource for extended documentation. 029 * 030 * <h5 class='section'>Example:</h5> 031 * <p class='bjava'> 032 * <jc>// Construct using SwaggerBuilder.</jc> 033 * ExternalDocumentation <jv>extDoc</jv> = <jsm>externalDocumentation</jsm>(<js>"https://swagger.io"</js>, <js>"Find more info here"</js>); 034 * 035 * <jc>// Serialize using JsonSerializer.</jc> 036 * String <jv>json</jv> = JsonSerializer.<jsf>DEFAULT</jsf>.toString(<jv>extDoc</jv>); 037 * 038 * <jc>// Or just use toString() which does the same as above.</jc> 039 * <jv>json</jv> = <jv>extDoc</jv>.toString(); 040 * </p> 041 * <p class='bjson'> 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><ul> 050 * <li class='link'><a class="doclink" href="../../../../../index.html#jrs.Swagger">Overview > juneau-rest-server > Swagger</a> 051 * </ul> 052 */ 053@Bean(properties="description,url,*") 054@FluentSetters 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 // Properties 088 //----------------------------------------------------------------------------------------------------------------- 089 090 /** 091 * Bean property getter: <property>description</property>. 092 * 093 * <p> 094 * A short description of the target documentation. 095 * 096 * @return The property value, or <jk>null</jk> if it is not set. 097 */ 098 public String getDescription() { 099 return description; 100 } 101 102 /** 103 * Bean property setter: <property>description</property>. 104 * 105 * <p> 106 * A short description of the target documentation. 107 * 108 * @param value 109 * The new value for this property. 110 * <br><a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used for rich text representation. 111 * <br>Can be <jk>null</jk> to unset the property. 112 * @return This object. 113 */ 114 public ExternalDocumentation setDescription(String value) { 115 description = value; 116 return this; 117 } 118 119 /** 120 * Bean property getter: <property>url</property>. 121 * 122 * <p> 123 * The URL for the target documentation. 124 * 125 * @return The property value, or <jk>null</jk> if it is not set. 126 */ 127 public URI getUrl() { 128 return url; 129 } 130 131 /** 132 * Bean property setter: <property>url</property>. 133 * 134 * <p> 135 * The URL for the target documentation. 136 * 137 * @param value 138 * The new value for this property. 139 * <br>Property value is required. 140 * <br>URIs defined by {@link UriResolver} can be used for values. 141 * @return This object. 142 */ 143 public ExternalDocumentation setUrl(URI value) { 144 url = value; 145 return this; 146 } 147 148 // <FluentSetters> 149 150 // </FluentSetters> 151 152 @Override /* SwaggerElement */ 153 public <T> T get(String property, Class<T> type) { 154 if (property == null) 155 return null; 156 switch (property) { 157 case "description": return toType(getDescription(), type); 158 case "url": return toType(getUrl(), type); 159 default: return super.get(property, type); 160 } 161 } 162 163 @Override /* SwaggerElement */ 164 public ExternalDocumentation set(String property, Object value) { 165 if (property == null) 166 return this; 167 switch (property) { 168 case "description": return setDescription(stringify(value)); 169 case "url": return setUrl(StringUtils.toURI(value)); 170 default: 171 super.set(property, value); 172 return this; 173 } 174 } 175 176 @Override /* SwaggerElement */ 177 public Set<String> keySet() { 178 Set<String> s = setBuilder(String.class) 179 .addIf(description != null, "description") 180 .addIf(url != null, "url") 181 .build(); 182 return new MultiSet<>(s, super.keySet()); 183 } 184}