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>@Rest</ja>-annotated classes.
027 *
028 * <h5 class='section'>Examples:</h5>
029 * <p class='bcode w800'>
030 *    <jc>// Normal</jc>
031 *    <ja>@Rest</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>@Rest</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 * <ul class='seealso'>
053 *    <li class='link'>{@doc RestSwagger}
054 *    <li class='extlink'>{@doc ExtSwaggerExternalDocumentationObject}
055 * </ul>
056 */
057@Documented
058@Retention(RUNTIME)
059public @interface ExternalDocs {
060
061   /**
062    * <mk>description</mk> field of the {@doc ExtSwaggerExternalDocumentationObject}.
063    *
064    * <p>
065    * A short description of the target documentation.
066    *
067    * <ul class='notes'>
068    *    <li>
069    *       The format is a plain-text string.
070    *       <br>Multiple lines are concatenated with newlines.
071    *    <li>
072    *       Supports {@doc RestSvlVariables}
073    *       (e.g. <js>"$L{my.localized.variable}"</js>).
074    * </ul>
075    */
076   String[] description() default {};
077
078   /**
079    * <mk>url</mk> field of the {@doc ExtSwaggerExternalDocumentationObject}.
080    *
081    * <p>
082    * The URL for the target documentation. Value MUST be in the format of a URL.
083    *
084    * <ul class='notes'>
085    *    <li>
086    *       The value is required.
087    *    <li>
088    *       The format is a URL string.
089    *    <li>
090    *       Supports {@doc RestSvlVariables}
091    *       (e.g. <js>"$L{my.localized.variable}"</js>).
092    * </ul>
093    */
094   String url() default "";
095
096   /**
097    * Free-form value for the {@doc ExtSwaggerExternalDocumentationObject}.
098    *
099    * <p>
100    * This is a {@doc SimplifiedJson} object that makes up the swagger information for this field.
101    *
102    * <p>
103    * The following are completely equivalent ways of defining the swagger description of documentation:
104    * <p class='bcode w800'>
105    *    <jc>// Normal</jc>
106    *    <ja>@Rest</ja>(
107    *       swagger=<ja>@ResourceSwagger</ja>(
108    *          externalDocs=<ja>@ExternalDocs</ja>(
109    *             description=<js>"Find out more about Juneau"</js>,
110    *             url=<js>"http://juneau.apache.org"</js>
111    *          )
112    *       )
113    *    )
114    * </p>
115    * <p class='bcode w800'>
116    *    <jc>// Free-form</jc>
117    *    <ja>@Rest</ja>(
118    *       swagger=<ja>@ResourceSwagger</ja>(
119    *          externalDocs=<ja>@ExternalDocs</ja>({
120    *             <js>"description: 'Find out more about Juneau',"</js>,
121    *             <js>"url: 'http://juneau.apache.org'"</js>
122    *          })
123    *       )
124    *    )
125    * </p>
126    * <p class='bcode w800'>
127    *    <jc>// Free-form with variables</jc>
128    *    <ja>@Rest</ja>(
129    *       swagger=<ja>@ResourceSwagger</ja>(
130    *          externalDocs=<ja>@ExternalDocs</ja>(<js>"$L{externalDocsSwagger}"</js>)
131    *       )
132    *    )
133    * </p>
134    * <p class='bcode w800'>
135    *    <mc>// Contents of MyResource.properties</mc>
136    *    <mk>externalDocsSwagger</mk> = <mv>{ description: "Find out more about Juneau", url: "http://juneau.apache.org" }</mv>
137    * </p>
138    *
139    * <p>
140    *    The reasons why you may want to use this field include:
141    * <ul>
142    *    <li>You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file.
143    *    <li>You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.
144    * </ul>
145    *
146    * <ul class='notes'>
147    *    <li>
148    *       The format is a {@doc SimplifiedJson} object.
149    *    <li>
150    *       The leading/trailing <c>{ }</c> characters are optional.
151    *       <br>The following two example are considered equivalent:
152    *       <p class='bcode w800'>
153    *    <ja>@ExternalDocs</ja>(<js>"{url:'http://juneau.apache.org'}"</js>)
154    *       </p>
155    *       <p class='bcode w800'>
156    *    <ja>@ExternalDocs</ja>(<js>"url:'http://juneau.apache.org'"</js>)
157    *       </p>
158    *    <li>
159    *       Multiple lines are concatenated with newlines so that you can format the value to be readable.
160    *    <li>
161    *       Supports {@doc RestSvlVariables}
162    *       (e.g. <js>"$L{my.localized.variable}"</js>).
163    *    <li>
164    *       Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.
165    * </ul>
166    */
167   String[] value() default {};
168}