From 16c212f853abc00a430520b01e7130c36e384545 Mon Sep 17 00:00:00 2001 From: Nikolay Kim Date: Sat, 31 Mar 2018 09:18:25 -0700 Subject: [PATCH] add extractors info to guide --- CHANGES.md | 3 +++ guide/src/qs_5.md | 23 +++++++++++++++++++++-- guide/src/qs_7.md | 33 ++++++++++++++++++++++++++++++--- src/json.rs | 2 -- src/pred.rs | 3 ++- src/server/mod.rs | 7 +++++++ src/ws/mod.rs | 2 +- 7 files changed, 64 insertions(+), 9 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index b424a3872..4acf464ad 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -4,6 +4,9 @@ * Type-safe path/query parameter handling, using serde #70 +* HttpResponse builder's methods `.body()`, `.finish()`, `.json()` + return `HttpResponse` instead of `Result` + * Use more ergonomic `actix_web::Error` instead of `http::Error` for `HttpResponseBuilder::body()` * Use more ergonomic `actix_web::Error` instead of `http::Error` for `ClientRequestBuilder::body()` diff --git a/guide/src/qs_5.md b/guide/src/qs_5.md index 67b3be79d..f97840a06 100644 --- a/guide/src/qs_5.md +++ b/guide/src/qs_5.md @@ -329,9 +329,7 @@ It uses *serde* package as a deserialization library. has to implement *serde's *`Deserialize` trait. ```rust -# extern crate bytes; # extern crate actix_web; -# extern crate futures; #[macro_use] extern crate serde_derive; use actix_web::{App, Path, Result, http::Method}; @@ -352,6 +350,27 @@ fn main() { } ``` +It also possible to extract path information to a tuple, in this case you don't need +to define extra type, just use tuple for as a `Path` generic type. + +Here is previous example re-written using tuple instead of specific type. + +```rust +# extern crate actix_web; +use actix_web::{App, Path, Result, http::Method}; + +// extract path info using serde +fn index(info: Path<(String, u32)>) -> Result { + Ok(format!("Welcome {}! id: {}", info.0, info.1)) +} + +fn main() { + let app = App::new() + .resource("/{username}/{id}/index.html", // <- define path parameters + |r| r.method(Method::GET).with(index)); +} +``` + [Query](../actix_web/struct.Query.html) provides similar functionality for request query parameters. diff --git a/guide/src/qs_7.md b/guide/src/qs_7.md index d841f2bd8..886d8b27c 100644 --- a/guide/src/qs_7.md +++ b/guide/src/qs_7.md @@ -58,9 +58,36 @@ fn index(req: HttpRequest) -> HttpResponse { ## JSON Request -There are two options for json body deserialization. +There are several options for json body deserialization. -The first option is to use *HttpResponse::json()*. This method returns a +The first option is to use *Json* extractor. You define handler function +that accepts `Json` as a parameter and use `.with()` method for registering +this handler. It is also possible to accept arbitrary valid json object by +using `serde_json::Value` as a type `T` + +```rust +# extern crate actix_web; +#[macro_use] extern crate serde_derive; +use actix_web::{App, Json, Result, http}; + +#[derive(Deserialize)] +struct Info { + username: String, +} + +/// extract `Info` using serde +fn index(info: Json) -> Result { + Ok(format!("Welcome {}!", info.username)) +} + +fn main() { + let app = App::new().resource( + "/index.html", + |r| r.method(http::Method::POST).with(index)); // <- use `with` extractor +} +``` + +The second option is to use *HttpResponse::json()*. This method returns a [*JsonBody*](../actix_web/dev/struct.JsonBody.html) object which resolves into the deserialized value. @@ -128,7 +155,7 @@ A complete example for both options is available in ## JSON Response -The `Json` type allows you to respond with well-formed JSON data: simply return a value of +The `Json` type allows to respond with well-formed JSON data: simply return a value of type Json where T is the type of a structure to serialize into *JSON*. The type `T` must implement the `Serialize` trait from *serde*. diff --git a/src/json.rs b/src/json.rs index 721361ffe..eb61da1b2 100644 --- a/src/json.rs +++ b/src/json.rs @@ -47,9 +47,7 @@ use httpresponse::HttpResponse; /// ## Example /// /// ```rust -/// # extern crate bytes; /// # extern crate actix_web; -/// # extern crate futures; /// #[macro_use] extern crate serde_derive; /// use actix_web::{App, Json, Result, http}; /// diff --git a/src/pred.rs b/src/pred.rs index 0c7468d0d..57398fc2b 100644 --- a/src/pred.rs +++ b/src/pred.rs @@ -8,7 +8,8 @@ use httprequest::HttpRequest; /// Trait defines resource route predicate. /// Predicate can modify request object. It is also possible to -/// to store extra attributes on request by using `.extensions()` method. +/// to store extra attributes on request by using `Extensions` container, +/// Extensions container available via `HttpRequest::extensions()` method. pub trait Predicate { /// Check if request matches predicate diff --git a/src/server/mod.rs b/src/server/mod.rs index fafcb9a27..96f53c5ff 100644 --- a/src/server/mod.rs +++ b/src/server/mod.rs @@ -126,12 +126,16 @@ impl HttpHandler for Box { } } +#[doc(hidden)] pub trait HttpHandlerTask { + /// Poll task, this method is used before or after *io* object is available fn poll(&mut self) -> Poll<(), Error>; + /// Poll task when *io* object is available fn poll_io(&mut self, io: &mut Writer) -> Poll; + /// Connection is disconnected fn disconnected(&mut self); } @@ -152,12 +156,14 @@ impl IntoHttpHandler for T { } } +#[doc(hidden)] #[derive(Debug)] pub enum WriterState { Done, Pause, } +#[doc(hidden)] /// Stream writer pub trait Writer { fn written(&self) -> u64; @@ -172,6 +178,7 @@ pub trait Writer { fn poll_completed(&mut self, shutdown: bool) -> Poll<(), io::Error>; } +#[doc(hidden)] /// Low-level io stream operations pub trait IoStream: AsyncRead + AsyncWrite + 'static { fn shutdown(&mut self, how: Shutdown) -> io::Result<()>; diff --git a/src/ws/mod.rs b/src/ws/mod.rs index c601236b6..9c5c74c53 100644 --- a/src/ws/mod.rs +++ b/src/ws/mod.rs @@ -10,7 +10,7 @@ //! # extern crate actix_web; //! # use actix::*; //! # use actix_web::*; -//! use actix_web::ws; +//! use actix_web::{ws, HttpRequest, HttpResponse}; //! //! // do websocket handshake and start actor //! fn ws_index(req: HttpRequest) -> Result {