Any Spring @RestController
in a Spring Boot application should render JSON response by
default as long as Jackson2 is on the classpath. For example:
@RestController public class MyController { @RequestMapping("/thing") public MyThing thing() { return new MyThing(); } }
As long as MyThing
can be serialized by Jackson2 (e.g. a normal POJO or Groovy object)
then localhost:8080/thing
will serve a JSON representation of it by default.
Sometimes in a browser you might see XML responses because browsers tend to send accept
headers that prefer XML.
If you have the Jackson XML extension (jackson-dataformat-xml
) on the classpath, it will
be used to render XML responses and the very same example as we used for JSON would work.
To use it, add the following dependency to your project:
<dependency> <groupId>com.fasterxml.jackson.dataformat</groupId> <artifactId>jackson-dataformat-xml</artifactId> </dependency>
You may also want to add a dependency on Woodstox. It’s faster than the default StAX implementation provided by the JDK and also adds pretty print support and improved namespace handling:
<dependency> <groupId>org.codehaus.woodstox</groupId> <artifactId>woodstox-core-asl</artifactId> </dependency>
If Jackson’s XML extension is not available, JAXB (provided by default in the JDK) will
be used, with the additional requirement to have MyThing
annotated as
@XmlRootElement
:
@XmlRootElement public class MyThing { private String name; // .. getters and setters }
To get the server to render XML instead of JSON you might have to send an
Accept: text/xml
header (or use a browser).
Spring MVC (client and server side) uses HttpMessageConverters
to negotiate content
conversion in an HTTP exchange. If Jackson is on the classpath you already get the
default converter(s) provided by Jackson2ObjectMapperBuilder
.
The ObjectMapper
(or XmlMapper
for Jackson XML converter) instance created by default
have the following customized properties:
MapperFeature.DEFAULT_VIEW_INCLUSION
is disabledDeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES
is disabledSpring Boot has also some features to make it easier to customize this behavior.
You can configure the ObjectMapper
and XmlMapper
instances using the environment.
Jackson provides an extensive suite of simple on/off features that can be used to
configure various aspects of its processing. These features are described in six enums in
Jackson which map onto properties in the environment:
Jackson enum | Environment property |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
For example, to enable pretty print, set spring.jackson.serialization.indent_output=true
.
Note that, thanks to the use of relaxed binding, the case of indent_output
doesn’t have to match the case of the
corresponding enum constant which is INDENT_OUTPUT
.
If you want to replace the default ObjectMapper
completely, define a @Bean
of that
type and mark it as @Primary
.
Defining a @Bean
of type Jackson2ObjectMapperBuilder
will allow you to customize both
default ObjectMapper
and XmlMapper
(used in MappingJackson2HttpMessageConverter
and
MappingJackson2XmlHttpMessageConverter
respectively).
Another way to customize Jackson is to add beans of type
com.fasterxml.jackson.databind.Module
to your context. They will be registered with every
bean of type ObjectMapper
, providing a global mechanism for contributing custom modules
when you add new features to your application.
Finally, if you provide any @Beans
of type MappingJackson2HttpMessageConverter
then
they will replace the default value in the MVC configuration. Also, a convenience bean is
provided of type HttpMessageConverters
(always available if you use the default MVC
configuration) which has some useful methods to access the default and user-enhanced
message converters.
See also the Section 71.4, “Customize the @ResponseBody rendering” section and the
WebMvcAutoConfiguration
source code for more details.
Spring uses HttpMessageConverters
to render @ResponseBody
(or responses from
@RestController
). You can contribute additional converters by simply adding beans of
that type in a Spring Boot context. If a bean you add is of a type that would have been
included by default anyway (like MappingJackson2HttpMessageConverter
for JSON
conversions) then it will replace the default value. A convenience bean is provided of
type HttpMessageConverters
(always available if you use the default MVC configuration)
which has some useful methods to access the default and user-enhanced message converters
(useful, for example if you want to manually inject them into a custom RestTemplate
).
As in normal MVC usage, any WebMvcConfigurerAdapter
beans that you provide can also
contribute converters by overriding the configureMessageConverters
method, but unlike
with normal MVC, you can supply only additional converters that you need (because Spring
Boot uses the same mechanism to contribute its defaults). Finally, if you opt-out of the
Spring Boot default MVC configuration by providing your own @EnableWebMvc
configuration,
then you can take control completely and do everything manually using
getMessageConverters
from WebMvcConfigurationSupport
.
See the WebMvcAutoConfiguration
source code for more details.
Spring Boot embraces the Servlet 3 javax.servlet.http.Part
API to support uploading
files. By default Spring Boot configures Spring MVC with a maximum file of 1Mb per
file and a maximum of 10Mb of file data in a single request. You may override these
values, as well as the location to which intermediate data is stored (e.g., to the /tmp
directory) and the threshold past which data is flushed to disk by using the properties
exposed in the MultipartProperties
class. If you want to specify that files be
unlimited, for example, set the multipart.maxFileSize
property to -1
.
The multipart support is helpful when you want to receive multipart encoded file data as
a @RequestParam
-annotated parameter of type MultipartFile
in a Spring MVC controller
handler method.
See the MultipartAutoConfiguration
source for more details.
Spring Boot wants to serve all content from the root of your application /
down. If you
would rather map your own servlet to that URL you can do it, but of course you may lose
some of the other Boot MVC features. To add your own servlet and map it to the root
resource just declare a @Bean
of type Servlet
and give it the special bean name
dispatcherServlet
(You can also create a bean of a different type with that name if
you want to switch it off and not replace it).
The easiest way to take complete control over MVC configuration is to provide your own
@Configuration
with the @EnableWebMvc
annotation. This will leave all MVC
configuration in your hands.
A ViewResolver
is a core component of Spring MVC, translating view names in
@Controller
to actual View
implementations. Note that ViewResolvers
are mainly
used in UI applications, rather than REST-style services (a View
is not used to render
a @ResponseBody
). There are many implementations of ViewResolver
to choose from, and
Spring on its own is not opinionated about which ones you should use. Spring Boot, on the
other hand, installs one or two for you depending on what it finds on the classpath and
in the application context. The DispatcherServlet
uses all the resolvers it finds in
the application context, trying each one in turn until it gets a result, so if you are
adding your own you have to be aware of the order and in which position your resolver is
added.
WebMvcAutoConfiguration
adds the following ViewResolvers
to your context:
InternalResourceViewResolver
with bean id ‘defaultViewResolver’. This one locates
physical resources that can be rendered using the DefaultServlet
(e.g. static
resources and JSP pages if you are using those). It applies a prefix and a suffix to the
view name and then looks for a physical resource with that path in the servlet context
(defaults are both empty, but accessible for external configuration via
spring.mvc.view.prefix
and spring.mvc.view.suffix
). It can be overridden by providing a
bean of the same type.BeanNameViewResolver
with id ‘beanNameViewResolver’. This is a useful member of the
view resolver chain and will pick up any beans with the same name as the View
being
resolved. It shouldn’t be necessary to override or replace it.ContentNegotiatingViewResolver
with id ‘viewResolver’ is only added if there are
actually beans of type View
present. This is a ‘master’ resolver, delegating to all
the others and attempting to find a match to the ‘Accept’ HTTP header sent by the
client. There is a useful
blog about ContentNegotiatingViewResolver
that you might like to study to learn more, and also look at the source code for detail.
You can switch off the auto-configured
ContentNegotiatingViewResolver
by defining a bean named ‘viewResolver’.ThymeleafViewResolver
with id
‘thymeleafViewResolver’. It looks for resources by surrounding the view name with a
prefix and suffix (externalized to spring.thymeleaf.prefix
and
spring.thymeleaf.suffix
, defaults ‘classpath:/templates/’ and ‘.html’
respectively). It can be overridden by providing a bean of the same name.FreeMarkerViewResolver
with id
‘freeMarkerViewResolver’. It looks for resources in a loader path (externalized to
spring.freemarker.templateLoaderPath
, default ‘classpath:/templates/’) by
surrounding the view name with a prefix and suffix (externalized to spring.freemarker.prefix
and spring.freemarker.suffix
, with empty and ‘.ftl’ defaults respectively). It can
be overridden by providing a bean of the same name.GroovyMarkupViewResolver
with id ‘groovyMarkupViewResolver’. It
looks for resources in a loader path by surrounding the view name with a prefix and
suffix (externalized to spring.groovy.template.prefix
and
spring.groovy.template.suffix
, defaults ‘classpath:/templates/’ and ‘.tpl’
respectively). It can be overridden by providing a bean of the same name.VelocityViewResolver
with id ‘velocityViewResolver’.
It looks for resources in a loader path (externalized to spring.velocity.resourceLoaderPath
,
default ‘classpath:/templates/’) by surrounding the view name with a prefix and suffix
(externalized to spring.velocity.prefix
and spring.velocity.suffix
, with empty and ‘.vm’
defaults respectively). It can be overridden by providing a bean of the same name.Check out WebMvcAutoConfiguration
,
ThymeleafAutoConfiguration
,
FreeMarkerAutoConfiguration
,
GroovyTemplateAutoConfiguration
and
VelocityAutoConfiguration
By default, Spring Boot configures a VelocityViewResolver
. If you need a
VelocityLayoutViewResolver
instead, you can easily configure your own by creating a bean
with name velocityViewResolver
. You can also inject the VelocityProperties
instance to
apply the base defaults to your custom view resolver.
The following example replaces the auto-configured velocity view resolver with a
VelocityLayoutViewResolver
defining a customized layoutUrl
and all settings that would
have been applied from the auto-configuration:
@Bean(name = "velocityViewResolver") public VelocityLayoutViewResolver velocityViewResolver(VelocityProperties properties) { VelocityLayoutViewResolver resolver = new VelocityLayoutViewResolver(); properties.applyToViewResolver(resolver); resolver.setLayoutUrl("layout/default.vm"); return resolver; }