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