Unverified Commit 4dc36bb1 authored by david-perez's avatar david-perez Committed by GitHub
Browse files

Improve documentation for the `aws-smithy-http-server` crate (#901) 

The changes are mostly stylistic. The only important change is that the
`routing` module and `Router::into_make_service` method have been made
doc-public, because users need to call `into_make_service` to feed the
returned `MakeService` to their `hyper` server.
parent e7afd8fe

rust-runtime/aws-smithy-http-server/src/error.rs

+1 −1
Original line number Diff line number Diff line
@@ -37,7 +37,7 @@ 
use crate::BoxError;

use std::{error::Error as StdError, fmt};



/// Errors that can happen when using `aws-smithy-server`.

/// Errors that can happen when using this crate.

#[derive(Debug)]

pub struct Error {

    inner: BoxError,

rust-runtime/aws-smithy-http-server/src/extension.rs

+3 −1
Original line number Diff line number Diff line
@@ -39,12 +39,14 @@ use async_trait::async_trait; 
use axum::extract::{FromRequest, RequestParts};

use std::ops::Deref;



/// Extractor that gets a value from request extensions.

/// Extractor that gets a value from [request extensions].

///

/// This is commonly used to share state across handlers.

///

/// If the extension is missing it will reject the request with a `500 Internal

/// Server Error` response.

///

/// [request extensions]: https://docs.rs/http/latest/http/struct.Extensions.html

#[derive(Debug, Clone, Copy)]

pub struct Extension<T>(pub T);

rust-runtime/aws-smithy-http-server/src/lib.rs

+3 −5
Original line number Diff line number Diff line
@@ -3,7 +3,9 @@ 
 * SPDX-License-Identifier: Apache-2.0.

 */



//! HTTP server runtime and utilities, loosely based on Axum.

//! HTTP server runtime and utilities, loosely based on [axum].

//!

//! [axum]: https://docs.rs/axum/latest/axum/



#[macro_use]

pub(crate) mod macros;
@@ -12,10 +14,6 @@ pub mod body; 
mod clone_box_service;

pub mod error;

mod extension;



// Only the code-generated operation registry should instantiate routers.

// We therefore hide it in the documentation.

#[doc(hidden)]

pub mod routing;



#[doc(hidden)]

rust-runtime/aws-smithy-http-server/src/macros.rs

+1 −1
Original line number Diff line number Diff line
@@ -32,7 +32,7 @@ 
 * DEALINGS IN THE SOFTWARE.

 */



//! Macros implementation

//! Macros implementation.



// Define a single rejection type

macro_rules! define_rejection {

rust-runtime/aws-smithy-http-server/src/rejection.rs

+8 −7
Original line number Diff line number Diff line
@@ -17,7 +17,7 @@ define_rejection! { 
define_rejection! {

    #[status = INTERNAL_SERVER_ERROR]

    #[body = "Headers taken by other extractor"]

    /// Rejection used if the headers have been taken by another extractor.

    /// Rejection type used if the headers have been taken by another extractor.

    pub struct HeadersAlreadyExtracted;

}
@@ -55,7 +55,7 @@ define_rejection! { 
    // TODO: we probably want to be more specific as the header parsing can have many variants

    #[status = BAD_REQUEST]

    #[body = "Error parsing headers"]

    /// Rejection used if the any of the header parsing fails.

    /// Rejection type used if the any of the header parsing fails.

    pub struct HeadersParse(Error);

}
@@ -90,7 +90,7 @@ define_rejection! { 
}



composite_rejection! {

    /// Rejection used for Content-Type errors such as missing Content-Type

    /// Rejection used for `Content-Type` errors such as missing `Content-Type`

    /// header, MIME parse issues, etc.

    pub enum ContentTypeRejection {

        MissingJsonContentType,
@@ -110,12 +110,13 @@ composite_rejection! { 
}



composite_rejection! {

    /// General rejection used as Rejection type in the Axum FromRequest / IntoResponse traits.

    /// General rejection type used by `smithy-rs` auto-generated extractors and responders.

    ///

    /// Contains one variant for each way the Smithy Rust server can fail.

    /// Contains one variant for each way extracting and responding can fail.

    ///

    /// This rejection aggregates all the errors that come from other smithy-rs runtime crate,

    /// allowing a nice integration with the ser/de and builders types generated by the codegen.

    /// This rejection type also aggregates all the errors that come from other `smithy-rs` runtime

    /// crates, allowing a nice integration with serialization, deserialization, and builder types

    /// generated by the codegen.

    pub enum SmithyRejection {

        Serialize,

        Deserialize,