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@RestResource(
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 @RestResource(title)
100      "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @RestResource(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   },
109
110   // Default stylesheet to use for the page.
111   // Can be overridden from external config file.
112   // Default is DevOps look-and-feel (aka Depression look-and-feel).
113   stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}",
114
115   // Default contents to add to the <head> section of the HTML page.
116   // Use it to add a favicon link to the page.
117   head="$C{REST/head}",
118
119   // No default page footer contents.
120   // Can be overridden from external config file.
121   footer="$C{REST/footer}",
122
123   // By default, table cell contents should not wrap.
124   nowrap="true"
125)
126public interface BasicRestConfig {
127
128   /**
129    * [OPTIONS /*] - Show resource options.
130    *
131    * @param req The HTTP request.
132    * @return A bean containing the contents for the OPTIONS page.
133    */
134   @RestMethod(name=OPTIONS, path="/*",
135      summary="Swagger documentation",
136      description="Swagger documentation for this resource."
137   )
138   @JsonSchemaConfig(
139      // Add descriptions to the following types when not specified:
140      addDescriptionsTo="bean,collection,array,map,enum",
141      // Add x-example to the following types:
142      addExamplesTo="bean,collection,array,map",
143      // Don't generate schema information on the Swagger bean itself or HTML beans.
144      ignoreTypes="Swagger,org.apache.juneau.dto.html5.*",
145      // Use $ref references for bean definitions to reduce duplication in Swagger.
146      useBeanDefs="true"
147   )
148   @BeanConfig(
149      // When parsing generated beans, ignore unknown properties that may only exist as getters and not setters.
150      ignoreUnknownBeanProperties="true",
151      // POJO swaps to apply to all serializers/parsers on this method.
152      pojoSwaps={
153         // Use the SwaggerUI swap when rendering Swagger beans.
154         // This is a per-media-type swap that only applies to text/html requests.
155         SwaggerUI.class
156      }
157   )
158   @HtmlDocConfig(
159      // Should override config annotations defined on class.
160      rank=10,
161      // Override the nav links for the swagger page.
162      navlinks={
163         "back: servlet:/",
164         "json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
165      },
166      // Never show aside contents of page inherited from class.
167      aside="NONE"
168   )
169   public Swagger getOptions(RestRequest req);
170}