001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http.annotation;
018
019import static java.lang.annotation.RetentionPolicy.*;
020
021import java.lang.annotation.*;
022
023/**
024 * Swagger contact annotation.
025 *
026 * <p>
027 * The contact information for the exposed API.
028 *
029 * <p>
030 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes.
031 *
032 * <h5 class='section'>Example:</h5>
033 * <p class='bjava'>
034 *    <ja>@Swagger</ja>(
035 *       contact=<ja>@Contact</ja>(
036 *          name=<js>"Juneau Development Team"</js>,
037 *          email=<js>"dev@juneau.apache.org"</js>,
038 *          url=<js>"http://juneau.apache.org"</js>
039 *       )
040 *    )
041 * </p>
042 *
043 * <h5 class='section'>See Also:</h5><ul>
044 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a>
045 *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#contactObject">Swagger Contact Object</a>
046
047 * </ul>
048 */
049@Documented
050@Retention(RUNTIME)
051public @interface Contact {
052
053    /**
054     * Optional description for the exposed API.
055     *
056     * @return The annotation value.
057     * @since 9.2.0
058     */
059    String[] description() default {};
060
061    /**
062    * <mk>email</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#contactObject">Swagger Contact Object</a>.
063    *
064    * <p>
065    * The email address of the contact person/organization. MUST be in the format of an email address.
066    *
067    * <h5 class='section'>Notes:</h5><ul>
068    *    <li class='note'>
069    *       The format is an email string.
070    *    <li class='note'>
071    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator.
072    * </ul>
073    *
074    * @return The annotation value.
075    */
076   String email() default "";
077
078   /**
079    * <mk>name</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#contactObject">Swagger Contact Object</a>.
080    *
081    * <p>
082    * The identifying name of the contact person/organization.
083    *
084    * <h5 class='section'>Notes:</h5><ul>
085    *    <li class='note'>
086    *       The format is a plain-text string.
087    *    <li class='note'>
088    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator.
089    * </ul>
090    *
091    * @return The annotation value.
092    */
093   String name() default "";
094
095   /**
096    * <mk>url</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#contactObject">Swagger Contact Object</a>.
097    *
098    * <p>
099    * The URL pointing to the contact information. MUST be in the format of a URL.
100    *
101    * <h5 class='section'>Notes:</h5><ul>
102    *    <li class='note'>
103    *       The format is a URL string.
104    *    <li class='note'>
105    *       Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a>
106    *       (e.g. <js>"$L{my.localized.variable}"</js>).
107    * </ul>
108    *
109    * @return The annotation value.
110    */
111   String url() default "";
112}