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.jsonschema.annotation; 014 015import static java.lang.annotation.RetentionPolicy.*; 016 017import java.lang.annotation.*; 018 019/** 020 * Swagger external documentation annotation. 021 * 022 * <p> 023 * Allows referencing an external resource for extended documentation. 024 * 025 * <p> 026 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@RestResource</ja>-annotated classes. 027 * 028 * <h5 class='section'>Examples:</h5> 029 * <p class='bcode w800'> 030 * <jc>// Normal</jc> 031 * <ja>@RestResource</ja>( 032 * swagger=<ja>@ResourceSwagger</ja>( 033 * externalDocs=<ja>@ExternalDocs</ja>( 034 * description=<js>"Apache Juneau"</js>, 035 * url=<js>"http://juneau.apache.org"</js> 036 * ) 037 * ) 038 * ) 039 * </p> 040 * <p class='bcode w800'> 041 * <jc>// Free-form</jc> 042 * <ja>@RestResource</ja>( 043 * swagger=<ja>@ResourceSwagger</ja>( 044 * contact=<ja>@ExternalDocs</ja>({ 045 * <js>"description:'Apache Juneau',"</js>, 046 * <js>"url:'http://juneau.apache.org'"</js>, 047 * }) 048 * ) 049 * ) 050 * </p> 051 * 052 * <h5 class='section'>See Also:</h5> 053 * <ul> 054 * <li class='link'>{@doc juneau-rest-server.Swagger} 055 * <li class='extlink'>{@doc SwaggerExternalDocumentationObject} 056 * </ul> 057 */ 058@Documented 059@Retention(RUNTIME) 060public @interface ExternalDocs { 061 062 /** 063 * <mk>description</mk> field of the {@doc SwaggerExternalDocumentationObject}. 064 * 065 * <p> 066 * A short description of the target documentation. 067 * 068 * <h5 class='section'>Notes:</h5> 069 * <ul class='spaced-list'> 070 * <li> 071 * The format is a plain-text string. 072 * <br>Multiple lines are concatenated with newlines. 073 * <li> 074 * Supports {@doc DefaultRestSvlVariables} 075 * (e.g. <js>"$L{my.localized.variable}"</js>). 076 * </ul> 077 */ 078 String[] description() default {}; 079 080 /** 081 * <mk>url</mk> field of the {@doc SwaggerExternalDocumentationObject}. 082 * 083 * <p> 084 * The URL for the target documentation. Value MUST be in the format of a URL. 085 * 086 * <h5 class='section'>Notes:</h5> 087 * <ul class='spaced-list'> 088 * <li> 089 * The value is required. 090 * <li> 091 * The format is a URL string. 092 * <li> 093 * Supports {@doc DefaultRestSvlVariables} 094 * (e.g. <js>"$L{my.localized.variable}"</js>). 095 * </ul> 096 */ 097 String url() default ""; 098 099 /** 100 * Free-form value for the {@doc SwaggerExternalDocumentationObject}. 101 * 102 * <p> 103 * This is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object that makes up the swagger information for this field. 104 * 105 * <p> 106 * The following are completely equivalent ways of defining the swagger description of documentation: 107 * <p class='bcode w800'> 108 * <jc>// Normal</jc> 109 * <ja>@RestResource</ja>( 110 * swagger=<ja>@ResourceSwagger</ja>( 111 * externalDocs=<ja>@ExternalDocs</ja>( 112 * description=<js>"Find out more about Juneau"</js>, 113 * url=<js>"http://juneau.apache.org"</js> 114 * ) 115 * ) 116 * ) 117 * </p> 118 * <p class='bcode w800'> 119 * <jc>// Free-form</jc> 120 * <ja>@RestResource</ja>( 121 * swagger=<ja>@ResourceSwagger</ja>( 122 * externalDocs=<ja>@ExternalDocs</ja>({ 123 * <js>"description: 'Find out more about Juneau',"</js>, 124 * <js>"url: 'http://juneau.apache.org'"</js> 125 * }) 126 * ) 127 * ) 128 * </p> 129 * <p class='bcode w800'> 130 * <jc>// Free-form with variables</jc> 131 * <ja>@RestResource</ja>( 132 * swagger=<ja>@ResourceSwagger</ja>( 133 * externalDocs=<ja>@ExternalDocs</ja>(<js>"$L{externalDocsSwagger}"</js>) 134 * ) 135 * ) 136 * </p> 137 * <p class='bcode w800'> 138 * <mc>// Contents of MyResource.properties</mc> 139 * <mk>externalDocsSwagger</mk> = <mv>{ description: "Find out more about Juneau", url: "http://juneau.apache.org" }</mv> 140 * </p> 141 * 142 * <p> 143 * The reasons why you may want to use this field include: 144 * <ul> 145 * <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file. 146 * <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification. 147 * </ul> 148 * 149 * <h5 class='section'>Notes:</h5> 150 * <ul class='spaced-list'> 151 * <li> 152 * The format is a {@doc juneau-marshall.JsonDetails.SimplifiedJson} object. 153 * <li> 154 * The leading/trailing <code>{ }</code> characters are optional. 155 * <br>The following two example are considered equivalent: 156 * <p class='bcode w800'> 157 * <ja>@ExternalDocs</ja>(<js>"{url:'http://juneau.apache.org'}"</js>) 158 * </p> 159 * <p class='bcode w800'> 160 * <ja>@ExternalDocs</ja>(<js>"url:'http://juneau.apache.org'"</js>) 161 * </p> 162 * <li> 163 * Multiple lines are concatenated with newlines so that you can format the value to be readable. 164 * <li> 165 * Supports {@doc DefaultRestSvlVariables} 166 * (e.g. <js>"$L{my.localized.variable}"</js>). 167 * <li> 168 * Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation. 169 * </ul> 170 */ 171 String[] value() default {}; 172}