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.HttpMethodName.*;
016
017import org.apache.juneau.annotation.*;
018import org.apache.juneau.dto.swagger.*;
019import org.apache.juneau.dto.swagger.ui.*;
020import org.apache.juneau.html.*;
021import org.apache.juneau.html.annotation.*;
022import org.apache.juneau.json.*;
023import org.apache.juneau.jsonschema.annotation.*;
024import org.apache.juneau.msgpack.*;
025import org.apache.juneau.oapi.*;
026import org.apache.juneau.plaintext.*;
027import org.apache.juneau.rest.annotation.*;
028import org.apache.juneau.serializer.annotation.*;
029import org.apache.juneau.soap.*;
030import org.apache.juneau.uon.*;
031import org.apache.juneau.urlencoding.*;
032import org.apache.juneau.xml.*;
033import org.apache.juneau.xmlschema.XmlSchemaDocSerializer;
034
035/**
036 * Basic configuration for a REST resource.
037 *
038 * <p>
039 * Classes that don't extend from {@link BasicRestServlet} can implement this interface to
040 * be configured with the same serializers/parsers/etc... as {@link BasicRestServlet}.
041 */
042@Rest(
043
044   // Default serializers for all Java methods in the class.
045   serializers={
046      HtmlDocSerializer.class, // HTML must be listed first because Internet Explore does not include text/html in their Accept header.
047      HtmlStrippedDocSerializer.class,
048      HtmlSchemaDocSerializer.class,
049      JsonSerializer.class,
050      SimpleJsonSerializer.class,
051      JsonSchemaSerializer.class,
052      XmlDocSerializer.class,
053      XmlSchemaDocSerializer.class,
054      UonSerializer.class,
055      UrlEncodingSerializer.class,
056      OpenApiSerializer.class,
057      MsgPackSerializer.class,
058      SoapXmlSerializer.class,
059      PlainTextSerializer.class
060   },
061
062   // Default parsers for all Java methods in the class.
063   parsers={
064      JsonParser.class,
065      JsonParser.Simple.class,
066      XmlParser.class,
067      HtmlParser.class,
068      UonParser.class,
069      UrlEncodingParser.class,
070      OpenApiParser.class,
071      MsgPackParser.class,
072      PlainTextParser.class
073   },
074
075   // Optional external configuration file.
076   config="$S{juneau.configFile,SYSTEM_DEFAULT}",
077
078   // These are static files that are served up by the servlet under the specified sub-paths.
079   // For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css"
080   // By default, we define static files through the external configuration file.
081   staticFiles="$C{REST/staticFiles,htdocs:/htdocs,htdocs:htdocs}",
082
083   logging=@Logging(
084      level="INFO",
085      useStackTraceHashing="true",
086      rules={
087         @LoggingRule(codes="500-", level="WARNING")
088      }
089   )
090)
091@SerializerConfig(
092   // Enable automatic resolution of URI objects to root-relative values.
093   uriResolution="ROOT_RELATIVE"
094)
095@HtmlDocConfig(
096
097   // Default page header contents.
098   header={
099      "<h1>$R{resourceTitle}</h1>",  // Use @Rest(title)
100      "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @Rest(description)
101      "$C{REST/header}"  // Extra header HTML defined in external config file.
102   },
103
104   // Basic page navigation links.
105   navlinks={
106      "up: request:/..",
107      "options: servlet:/?method=OPTIONS",
108      "stats: servlet:/stats"
109   },
110
111   // Default stylesheet to use for the page.
112   // Can be overridden from external config file.
113   // Default is DevOps look-and-feel (aka Depression look-and-feel).
114   stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}",
115
116   // Default contents to add to the <head> section of the HTML page.
117   // Use it to add a favicon link to the page.
118   head="$C{REST/head}",
119
120   // No default page footer contents.
121   // Can be overridden from external config file.
122   footer="$C{REST/footer}",
123
124   // By default, table cell contents should not wrap.
125   nowrap="true"
126)
127@JsonSchemaConfig(
128   // Add descriptions to the following types when not specified:
129   addDescriptionsTo="bean,collection,array,map,enum",
130   // Add x-example to the following types:
131   addExamplesTo="bean,collection,array,map",
132   // Don't generate schema information on the Swagger bean itself or HTML beans.
133   ignoreTypes="Swagger,org.apache.juneau.dto.html5.*",
134   // Use $ref references for bean definitions to reduce duplication in Swagger.
135   useBeanDefs="true"
136)
137@BeanConfig(
138   // When parsing generated beans, ignore unknown properties that may only exist as getters and not setters.
139   ignoreUnknownBeanProperties="true",
140   // POJO swaps to apply to all serializers/parsers on this method.
141   pojoSwaps={
142      // Use the SwaggerUI swap when rendering Swagger beans.
143      // This is a per-media-type swap that only applies to text/html requests.
144      SwaggerUI.class
145   }
146)
147public interface BasicRestConfig {
148
149   /**
150    * [OPTIONS /*] - Show resource options.
151    *
152    * @param req The HTTP request.
153    * @return A bean containing the contents for the OPTIONS page.
154    */
155   @RestMethod(name=OPTIONS, path="/*",
156      summary="Swagger documentation",
157      description="Swagger documentation for this resource."
158   )
159   @HtmlDocConfig(
160      // Should override config annotations defined on class.
161      rank=10,
162      // Override the nav links for the swagger page.
163      navlinks={
164         "back: servlet:/",
165         "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
166      },
167      // Never show aside contents of page inherited from class.
168      aside="NONE"
169   )
170   public Swagger getOptions(RestRequest req);
171
172   /**
173    * [* /error] - Error occurred.
174    *
175    * <p>
176    * Servlet chains will often automatically redirect to <js>"/error"</js> when any sort of error condition occurs
177    * (such as failed authentication) and will set appropriate response parameters (such as an <c>WWW-Authenticate</c>
178    * response header).
179    *
180    * <p>
181    * These responses should be left as-is without any additional processing.
182    */
183   @RestMethod(name=ANY, path="/error",
184      summary="Error occurred",
185      description="An error occurred during handling of the request."
186   )
187   public void error();
188
189   /**
190    * [GET /stats] - Timing statistics.
191    *
192    * <p>
193    * Timing statistics for method invocations on this resource.
194    *
195    * @param req The HTTP request.
196    * @return A collection of timing statistics for each annotated method on this resource.
197    */
198   @RestMethod(name=GET, path="/stats",
199      summary="Timing statistics",
200      description="Timing statistics for method invocations on this resource."
201   )
202   @HtmlDocConfig(
203      // Should override config annotations defined on class.
204      rank=10,
205      // Override the nav links for the swagger page.
206      navlinks={
207         "back: servlet:/",
208         "json: servlet:/stats?Accept=text/json&plainText=true"
209      },
210      // Never show aside contents of page inherited from class.
211      aside="NONE"
212   )
213   public RestContextStats getStats(RestRequest req);
214}