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.rest;
014
015import static org.apache.juneau.http.HttpMethod.*;
016
017import org.apache.juneau.annotation.*;
018import org.apache.juneau.dto.swagger.*;
019import org.apache.juneau.dto.swagger.ui.*;
020import org.apache.juneau.html.annotation.*;
021import org.apache.juneau.jsonschema.annotation.*;
022import org.apache.juneau.rest.annotation.*;
023
024/**
025 * TODO
026 */
027@HtmlDocConfig(
028
029   // Basic page navigation links.
030   navlinks={
031      "up: request:/..",
032      "options: servlet:/?method=OPTIONS",
033      "stats: servlet:/stats"
034   }
035
036)
037@JsonSchemaConfig(
038   // Add descriptions to the following types when not specified:
039   addDescriptionsTo="bean,collection,array,map,enum",
040   // Add x-example to the following types:
041   addExamplesTo="bean,collection,array,map",
042   // Don't generate schema information on the Swagger bean itself or HTML beans.
043   ignoreTypes="Swagger,org.apache.juneau.dto.html5.*",
044   // Use $ref references for bean definitions to reduce duplication in Swagger.
045   useBeanDefs="true"
046)
047@BeanConfig(
048   // POJO swaps to apply to all serializers/parsers on this method.
049   swaps={
050      // Use the SwaggerUI swap when rendering Swagger beans.
051      // This is a per-media-type swap that only applies to text/html requests.
052      SwaggerUI.class
053   }
054)
055public interface BasicRestMethods {
056
057   /**
058    * [OPTIONS /*] - Show resource options.
059    *
060    * @param req The HTTP request.
061    * @return A bean containing the contents for the OPTIONS page.
062    */
063   @RestMethod(name=OPTIONS, path="/*",
064      summary="Swagger documentation",
065      description="Swagger documentation for this resource."
066   )
067   @HtmlDocConfig(
068      // Should override config annotations defined on class.
069      rank=10,
070      // Override the nav links for the swagger page.
071      navlinks={
072         "back: servlet:/",
073         "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
074      },
075      // Never show aside contents of page inherited from class.
076      aside="NONE"
077   )
078   public Swagger getOptions(RestRequest req);
079
080   /**
081    * [GET /options] - Show resource options.
082    *
083    * @param req The HTTP request.
084    * @return A bean containing the contents for the OPTIONS page.
085    */
086   @RestMethod(name=OPTIONS, path="/*",
087      summary="Swagger documentation",
088      description="Swagger documentation for this resource."
089   )
090   @HtmlDocConfig(
091      // Should override config annotations defined on class.
092      rank=10,
093      // Override the nav links for the swagger page.
094      navlinks={
095         "back: servlet:/",
096         "json: servlet:/?Accept=text/json&plainText=true"
097      },
098      // Never show aside contents of page inherited from class.
099      aside="NONE"
100   )
101   public Swagger getOptions2(RestRequest req);
102
103   /**
104    * [* /error] - Error occurred.
105    *
106    * <p>
107    * Servlet chains will often automatically redirect to <js>"/error"</js> when any sort of error condition occurs
108    * (such as failed authentication) and will set appropriate response parameters (such as an <c>WWW-Authenticate</c>
109    * response header).
110    *
111    * <p>
112    * These responses should be left as-is without any additional processing.
113    */
114   @RestMethod(name=ANY, path="/error",
115      summary="Error occurred",
116      description="An error occurred during handling of the request."
117   )
118   public void error();
119
120   /**
121    * [GET /stats] - Timing statistics.
122    *
123    * <p>
124    * Timing statistics for method invocations on this resource.
125    *
126    * @param req The HTTP request.
127    * @return A collection of timing statistics for each annotated method on this resource.
128    */
129   @RestMethod(name=GET, path="/stats",
130      summary="Timing statistics",
131      description="Timing statistics for method invocations on this resource."
132   )
133   @HtmlDocConfig(
134      // Should override config annotations defined on class.
135      rank=10,
136      // Override the nav links for the swagger page.
137      navlinks={
138         "back: servlet:/",
139         "json: servlet:/stats?Accept=text/json&plainText=true"
140      },
141      // Never show aside contents of page inherited from class.
142      aside="NONE"
143   )
144   public RestContextStats getStats(RestRequest req);
145
146}