From ae221549791e84c994848697eb9123f766dcb98d Mon Sep 17 00:00:00 2001
From: David Pedersen <david.pdrsn@gmail.com>
Date: Fri, 4 Mar 2022 10:53:17 +0100
Subject: [PATCH] Add example for implementing `IntoResponseParts` (#825)

---
 axum-core/src/response/into_response_parts.rs | 61 +++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/axum-core/src/response/into_response_parts.rs b/axum-core/src/response/into_response_parts.rs
index 6022ea57..5810bef7 100644
--- a/axum-core/src/response/into_response_parts.rs
+++ b/axum-core/src/response/into_response_parts.rs
@@ -9,6 +9,67 @@ use std::{
 };
 
 /// Trait for adding headers and extensions to a response.
+///
+/// # Example
+///
+/// ```rust
+/// use axum::{
+///     response::{ResponseParts, IntoResponse, IntoResponseParts, Response},
+///     http::{StatusCode, header::{HeaderName, HeaderValue}},
+/// };
+///
+/// // Hypothetical helper type for setting a single header
+/// struct SetHeader<'a>(&'a str, &'a str);
+///
+/// impl<'a> IntoResponseParts for SetHeader<'a> {
+///     type Error = (StatusCode, String);
+///
+///     fn into_response_parts(self, mut res: ResponseParts) -> Result<ResponseParts, Self::Error> {
+///         match (self.0.parse::<HeaderName>(), self.1.parse::<HeaderValue>()) {
+///             (Ok(name), Ok(value)) => {
+///                 res.headers_mut().insert(name, value);
+///             },
+///             (Err(_), _) => {
+///                 return Err((
+///                     StatusCode::INTERNAL_SERVER_ERROR,
+///                     format!("Invalid header name {}", self.0),
+///                 ));
+///             },
+///             (_, Err(_)) => {
+///                 return Err((
+///                     StatusCode::INTERNAL_SERVER_ERROR,
+///                     format!("Invalid header value {}", self.1),
+///                 ));
+///             },
+///         }
+///
+///         Ok(res)
+///     }
+/// }
+///
+/// // Its also recommended to implement `IntoResponse` so `SetHeader` can be used on its own as
+/// // the response
+/// impl<'a> IntoResponse for SetHeader<'a> {
+///     fn into_response(self) -> Response {
+///         // This gives an empty response with the header
+///         (self, ()).into_response()
+///     }
+/// }
+///
+/// // We can now return `SetHeader` in responses
+/// async fn handler() -> impl IntoResponse {
+///     (
+///         SetHeader("server", "axum"),
+///         SetHeader("x-foo", "custom"),
+///         "body",
+///     )
+/// }
+///
+/// // Or on its own as the whole response
+/// async fn other_handler() -> impl IntoResponse {
+///     SetHeader("x-foo", "custom")
+/// }
+/// ```
 pub trait IntoResponseParts {
     /// The type returned in the event of an error.
     ///