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}