tchekai704
/
src-spring-framework
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

Revise docs on RFC 7807 

See gh-28814
pull/29282/head
rstoyanchev 2 years ago
parent
a4210854fb
commit
75dea98811
2 changed files with 87 additions and 82 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 84
      src/docs/asciidoc/web/webflux.adoc
  2. 85
      src/docs/asciidoc/web/webmvc.adoc

84
src/docs/asciidoc/web/webflux.adoc
Unescape View File

@ -3495,47 +3495,49 @@ include::webflux-cors.adoc[leveloffset=+1] @@ -3495,47 +3495,49 @@ include::webflux-cors.adoc[leveloffset=+1]
== REST API exceptions
[.small]#<<web.adoc#mvc-ann-rest-exceptions, Web MVC>>#
A common requirement for REST services is to include error details in the body of the
response. The Spring Framework provides support for
https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807] formatted error responses.
Main abstractions and supporting infrastructure:
- `ProblemDetail` in the `spring-web` module is the core abstraction that represents an
RFC 7807 problem detail. It helps to enable a range of features in Spring WebFlux for the
handling and rendering of such responses.
- `ErrorResponse` is an interface that defines an error response, including status, headers,
and `ProblemDetail` as its body. All Spring web exceptions implement this interface, and
thus encapsulate a default opinion on how they map to an RFC 7807 error response.
- `ErrorResponseException` is a `RuntimeException` that implements `ErrorResponse`, which
can be raised directly or serve as a base class for other exceptions.
- {api-spring-framework}/web/reactive/result/method/annotation/ResponseEntityExceptionHandler.html[`ResponseEntityExceptionHandler`]
provides handling for Spring WebFlux exceptions and for any `ErrorResponseException`.
Applications can extend this as an <<webflux-ann-controller-advice>> to enable RFC 7807 support.
`ProblemDetail` and `ErrorResponse` are supported as return values from
`@ExceptionHandler` and `@RequestMapping` controller methods. The `status` property of
`ProblemDetail` is used to set the response status, while the `instance` property is set
from the current URL path, if not already set.
The Jackson `Encoder` returns "application/problem+json" as a preferred
choice to serialize `ProblemDetail` to JSON as part of content negotiation. If no suitable
media type is found to render a `ProblemDetail` response body, content negotiation falls
back on "application/problem+json".
Applications can extend `ProblemDetail` with non-standard fields in one of two ways:
. Add properties to the generic `properties` map in `ProblemDetail`. When the Jackson JSON
library is present, this `properties` map is unwrapped and rendered as top level
key-value pairs in the output JSON, with the help of `ProblemDetailJacksonMixin`.
. Create a `ProblemDetail` subclass that defines the extra, non-standard fields.
Subclasses can use a protected copy constructor in order to re-create an existing
`ProblemDetail` as a subclass. This can be done centrally from an `@ControllerAdvice`
such as `ResponseEntityExceptionHandler`.
On the client side, `WebClientResponseException` provides methods that decode the response
body to some target type. This is useful to decode to a `ProblemDetail`, or to any other
class, including subclasses of `ProblemDetail`.
A common requirement for REST services is to include details in the body of an error
response. The Spring Framework supports the "Problem Details for HTTP APIs"
specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. These are the main
abstractions for this support:
- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container
for both standard fields defined in the spec, and for non-standard ones.
- `ErrorResponse` -- contract to expose HTTP error response details including HTTP
status, response headers, and a body in the format of RFC 7807; this allows exceptions to
encapsulate and expose the details of how they map to an HTTP response. All Spring MVC
exceptions implement this.
- `ErrorResponseException` -- basic `ErrorResponse` implementation that others
can use as a convenient base class.
- `ResponseEntityExceptionHandler` -- convenient base class for an
<<webflux-ann-controller-advice,@ControllerAdvice>> that handles all Spring MVC exceptions,
and any `ErrorResponseException`, and renders an error response with a body.
You can return `ProblemDetail` or `ErrorResponse` directly from `@RequestMapping` or
from `@ExceptionHandler` controller methods to render an RFC 7807 response as follows:
- The `status` property of `ProblemDetail` determines the HTTP status.
- The `instance` property of `ProblemDetail` is set from the current URL path, if not
already set.
- For content negotiation, the Jackson `HttpMessageConverter` prefers
"application/problem+json" over "application/json" when rendering a `ProblemDetail`,
and also falls back on it if no compatible media type is found.
You can extend an RFC 7807 response with non-standard fields as follows:
- Insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson
library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this
"properties" `Map` is unwrapped and rendered as top level JSON properties in the
response, and likewise any unknown property during deserialization is inserted into
this `Map`.
- Extend `ProblemDetail` to add dedicated non-standard properties. The copy constructor
in `ProblemDetail` allows a sub-class to make it easy to be created from an existing
`ProblemDetail`. This could be done centrally, e.g. from an `@ControllerAdvice` such as
`ResponseEntityExceptionHandler` that re-creates the `ProblemDetail` of an exception into
a subclass with the additional non-standard fields.
A client application can catch `WebClientResponseException` and use its
`getResponseBodyAs` methods to decode the error response body to any target type such as
`ProblemDetail`, or a subclass of `ProblemDetail`.

85
src/docs/asciidoc/web/webmvc.adoc
Unescape View File

@ -4827,47 +4827,50 @@ include::webmvc-cors.adoc[leveloffset=+1] @@ -4827,47 +4827,50 @@ include::webmvc-cors.adoc[leveloffset=+1]
== REST API exceptions
[.small]#<<web-reactive.adoc#webflux-ann-rest-exceptions, WebFlux>>#
A common requirement for REST services is to include error details in the body of the
response. The Spring Framework provides support for
https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807] formatted error responses.
Main abstractions and supporting infrastructure:
- `ProblemDetail` in the `spring-web` module is the core abstraction that represents an
RFC 7807 problem detail. It helps to enable a range of features in Spring MVC for the
handling and rendering of such responses.
- `ErrorResponse` is an interface that defines an error response, including status, headers,
and `ProblemDetail` as its body. All Spring web exceptions implement this interface, and
thus encapsulate a default opinion on how they map to an RFC 7807 error response.
- `ErrorResponseException` is a `RuntimeException` that implements `ErrorResponse`, which
can be raised directly or serve as a base class for other exceptions.
- {api-spring-framework}/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.html[`ResponseEntityExceptionHandler`]
provides handling for Spring MVC exceptions and for any `ErrorResponseException`.
Applications can extend this as an <<mvc-ann-controller-advice>> to enable RFC 7807 support.
`ProblemDetail` and `ErrorResponse` are supported as return values from
`@ExceptionHandler` and `@RequestMapping` controller methods. The `status` property of
`ProblemDetail` is used to set the response status, while the `instance` property is set
from the current URL path, if not already set.
The Jackson `HttpMessageConverter` returns "application/problem+json" as a preferred
choice to serialize `ProblemDetail` to JSON as part of content negotiation. If no suitable
media type is found to render a `ProblemDetail` response body, content negotiation falls
back on "application/problem+json".
Applications can extend `ProblemDetail` with non-standard fields in one of two ways:
. Add properties to the generic `properties` map in `ProblemDetail`. When using
the Jackson library, this `properties` map is unwrapped and as top level JSON
properties with the help of `ProblemDetailJacksonMixin`.
. Create a `ProblemDetail` subclass that defines the extra, non-standard fields.
Subclasses can use a protected copy constructor in order to re-create an existing
`ProblemDetail` as a subclass. This can be done centrally from an `@ControllerAdvice`
such as `ResponseEntityExceptionHandler`.
On the client side, `WebClientResponseException` and `RestClientResponseException` provide
methods that decode the response body to some target type. This is useful to decode to a
`ProblemDetail`, or to any other class, including subclasses of `ProblemDetail`.
A common requirement for REST services is to include details in the body of an error
response. The Spring Framework supports the "Problem Details for HTTP APIs"
specification, https://www.rfc-editor.org/rfc/rfc7807.html[RFC 7807]. These are the main
abstractions for this support:
- `ProblemDetail` -- representation for an RFC 7807 problem detail; a simple container
for both standard fields defined in the spec, and for non-standard ones.
- `ErrorResponse` -- contract to expose HTTP error response details including HTTP
status, response headers, and a body in the format of RFC 7807; this allows exceptions to
encapsulate and expose the details of how they map to an HTTP response. All Spring MVC
exceptions implement this.
- `ErrorResponseException` -- basic `ErrorResponse` implementation that others
can use as a convenient base class.
- `ResponseEntityExceptionHandler` -- convenient base class for an
<<mvc-ann-controller-advice,@ControllerAdvice>> that handles all Spring MVC exceptions,
and any `ErrorResponseException`, and renders an error response with a body.
You can return `ProblemDetail` or `ErrorResponse` directly from `@RequestMapping` or
from `@ExceptionHandler` controller methods to render an RFC 7807 response as follows:
- The `status` property of `ProblemDetail` determines the HTTP status.
- The `instance` property of `ProblemDetail` is set from the current URL path, if not
already set.
- For content negotiation, the Jackson `HttpMessageConverter` prefers
"application/problem+json" over "application/json" when rendering a `ProblemDetail`,
and also falls back on it if no compatible media type is found.
You can extend an RFC 7807 response with non-standard fields as follows:
- Insert into the "properties" `Map` of `ProblemDetail`. When using the Jackson
library, the Spring Framework registers `ProblemDetailJacksonMixin` that ensures this
"properties" `Map` is unwrapped and rendered as top level JSON properties in the
response, and likewise any unknown property during deserialization is inserted into
this `Map`.
- Extend `ProblemDetail` to add dedicated non-standard properties. The copy constructor
in `ProblemDetail` allows a sub-class to make it easy to be created from an existing
`ProblemDetail`. This could be done centrally, e.g. from an `@ControllerAdvice` such as
`ResponseEntityExceptionHandler` that re-creates the `ProblemDetail` of an exception into
a subclass with the additional non-standard fields.
A client application can catch `WebClientResponseException`, when using the `WebClient`,
or `RestClientResponseException` when using the `RestTemplate`, and use their
`getResponseBodyAs` methods to decode the error response body to any target type such as
`ProblemDetail`, or a subclass of `ProblemDetail`.

Write Preview
Loading…
Cancel
Save