From f988df9687dcefc4aea00e25d9e2a6f9e991c201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=ABl=20Schulz-Andres?= Date: Tue, 5 Aug 2025 17:37:07 +0200 Subject: [PATCH 1/4] [docs] update extractor docs: fix a typo, increase verbosity --- dropshot/src/extractor/body.rs | 8 +++++--- dropshot/src/extractor/path.rs | 10 ++++++---- dropshot/src/extractor/query.rs | 9 ++++++--- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/dropshot/src/extractor/body.rs b/dropshot/src/extractor/body.rs index 144e7415b..75ea2c743 100644 --- a/dropshot/src/extractor/body.rs +++ b/dropshot/src/extractor/body.rs @@ -30,9 +30,11 @@ use std::fmt::Debug; // type. Only JSON is currently supported. /// `TypedBody` is an extractor used to deserialize an instance of -/// `BodyType` from an HTTP request body. `BodyType` is any structure of yours -/// that implements `serde::Deserialize`. See this module's documentation for -/// more information. +/// `BodyType` from an HTTP request body. `BodyType` may be any struct of yours +/// that implements [serde::Deserialize] and [schemars::JsonSchema], where +/// primitives and enums have to be wrapped in an outer struct and enums need +/// to be flattened using the `#[serde(flatten)]` attribute. See this module's +/// documentation formore information. #[derive(Debug)] pub struct TypedBody { inner: BodyType, diff --git a/dropshot/src/extractor/path.rs b/dropshot/src/extractor/path.rs index 7ffbc9efe..691790fc0 100644 --- a/dropshot/src/extractor/path.rs +++ b/dropshot/src/extractor/path.rs @@ -16,10 +16,12 @@ use schemars::JsonSchema; use serde::de::DeserializeOwned; use std::fmt::Debug; -/// `Path` is an extractor used to deserialize an instance of -/// `PathType` from an HTTP request's path parameters. `PathType` is any -/// structure of yours that implements [serde::Deserialize] and -/// [schemars::JsonSchema]. See the crate documentation for more information. +/// `Path` is an extractor used to deserialize an instance of +/// `PathType` from an HTTP request's path parameters. `PathType` may be any +/// struct of yours that implements [serde::Deserialize] and +/// [schemars::JsonSchema], where primitives and enums have to be wrapped in an +/// outer struct and enums need to be flattened using the `#[serde(flatten)]` +/// attribute. See this module's documentation formore information. #[derive(Debug)] pub struct Path { inner: PathType, diff --git a/dropshot/src/extractor/query.rs b/dropshot/src/extractor/query.rs index 3fbd7cb9b..c4bdf32f1 100644 --- a/dropshot/src/extractor/query.rs +++ b/dropshot/src/extractor/query.rs @@ -17,9 +17,12 @@ use serde::de::DeserializeOwned; use std::fmt::Debug; /// `Query` is an extractor used to deserialize an instance of -/// `QueryType` from an HTTP request's query string. `QueryType` is any -/// structure of yours that implements [serde::Deserialize] and -/// [schemars::JsonSchema]. See the crate documentation for more information. +/// `QueryType` from an HTTP request's query string. `QueryType` may be any +/// struct of yours that implements [serde::Deserialize] and +/// [schemars::JsonSchema], where primitives and enums have to be wrapped in +/// an outer struct and enums need to be flattened using the +/// `#[serde(flatten)]` attribute. See this module's documentation for more +/// information. #[derive(Debug)] pub struct Query { inner: QueryType, From 6bf0830b8610fe01c655724a78fec3b573d70191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=ABl=20Schulz-Andres?= Date: Mon, 1 Sep 2025 20:32:29 +0200 Subject: [PATCH 2/4] implement review from @davepacheco --- dropshot/src/extractor/body.rs | 7 ++----- dropshot/src/extractor/header.rs | 7 ++++--- dropshot/src/extractor/path.rs | 5 ++--- dropshot/src/extractor/query.rs | 6 ++---- dropshot/src/lib.rs | 16 +++++++++++++--- 5 files changed, 23 insertions(+), 18 deletions(-) diff --git a/dropshot/src/extractor/body.rs b/dropshot/src/extractor/body.rs index 75ea2c743..e37040dac 100644 --- a/dropshot/src/extractor/body.rs +++ b/dropshot/src/extractor/body.rs @@ -28,13 +28,10 @@ use std::fmt::Debug; // TypedBody: body extractor for formats that can be deserialized to a specific // type. Only JSON is currently supported. - /// `TypedBody` is an extractor used to deserialize an instance of /// `BodyType` from an HTTP request body. `BodyType` may be any struct of yours -/// that implements [serde::Deserialize] and [schemars::JsonSchema], where -/// primitives and enums have to be wrapped in an outer struct and enums need -/// to be flattened using the `#[serde(flatten)]` attribute. See this module's -/// documentation formore information. +/// that implements [serde::Deserialize] and [schemars::JsonSchema]. +/// See this module's documentation for more information. #[derive(Debug)] pub struct TypedBody { inner: BodyType, diff --git a/dropshot/src/extractor/header.rs b/dropshot/src/extractor/header.rs index e8da8691b..644db0132 100644 --- a/dropshot/src/extractor/header.rs +++ b/dropshot/src/extractor/header.rs @@ -19,9 +19,10 @@ use super::{metadata::get_metadata, ExtractorMetadata, SharedExtractor}; /// `Header` is an extractor used to deserialize an instance of /// `HeaderType` from an HTTP request's header values. `HeaderType` may be any /// structure that implements [serde::Deserialize] and [schemars::JsonSchema]. -/// While headers are accessible through [RequestInfo::headers], using this -/// extractor in an entrypoint causes header inputs to be documented in -/// OpenAPI output. See the crate documentation for more information. +/// While headers are always accessible through [RequestInfo::headers] even +/// without this extractor, using this extractor causes header inputs to be +/// documented in OpenAPI output. +/// See the top-level crate documentation for more information. /// /// Note that (unlike the [`Query`] and [`Path`] extractors) headers are case- /// insensitive. You may rename fields with mixed casing (e.g. by using diff --git a/dropshot/src/extractor/path.rs b/dropshot/src/extractor/path.rs index 691790fc0..acff04e20 100644 --- a/dropshot/src/extractor/path.rs +++ b/dropshot/src/extractor/path.rs @@ -19,9 +19,8 @@ use std::fmt::Debug; /// `Path` is an extractor used to deserialize an instance of /// `PathType` from an HTTP request's path parameters. `PathType` may be any /// struct of yours that implements [serde::Deserialize] and -/// [schemars::JsonSchema], where primitives and enums have to be wrapped in an -/// outer struct and enums need to be flattened using the `#[serde(flatten)]` -/// attribute. See this module's documentation formore information. +/// [schemars::JsonSchema]. +/// See the top-level crate documentation for more information. #[derive(Debug)] pub struct Path { inner: PathType, diff --git a/dropshot/src/extractor/query.rs b/dropshot/src/extractor/query.rs index c4bdf32f1..939764094 100644 --- a/dropshot/src/extractor/query.rs +++ b/dropshot/src/extractor/query.rs @@ -19,10 +19,8 @@ use std::fmt::Debug; /// `Query` is an extractor used to deserialize an instance of /// `QueryType` from an HTTP request's query string. `QueryType` may be any /// struct of yours that implements [serde::Deserialize] and -/// [schemars::JsonSchema], where primitives and enums have to be wrapped in -/// an outer struct and enums need to be flattened using the -/// `#[serde(flatten)]` attribute. See this module's documentation for more -/// information. +/// [schemars::JsonSchema]. +/// See the top-level crate documentation for more information. #[derive(Debug)] pub struct Query { inner: QueryType, diff --git a/dropshot/src/lib.rs b/dropshot/src/lib.rs index c8999c687..c8addfe13 100644 --- a/dropshot/src/lib.rs +++ b/dropshot/src/lib.rs @@ -323,13 +323,14 @@ //! //! * [`Query`]`` extracts parameters from a query string, deserializing them //! into an instance of type `Q`. `Q` must implement `serde::Deserialize` and -//! `schemars::JsonSchema`. +//! `schemars::JsonSchema`. See below for additional restrictions. //! * [`Path`]`

` extracts parameters from HTTP path, deserializing them into //! an instance of type `P`. `P` must implement `serde::Deserialize` and -//! `schemars::JsonSchema`. +//! `schemars::JsonSchema`. See below for additional restrictions. //! * [`Header`]`` extracts parameters from HTTP headers, deserializing //! them into an instance of type `H`. `H` must implement -//! `serde::Deserialize` and `schemars::JsonSchema`. +//! `serde::Deserialize` and `schemars::JsonSchema`. See below for additional +//! restrictions. //! * [`TypedBody`]`` extracts content from the request body by parsing the //! body as JSON (or form/url-encoded) and deserializing it into an instance //! of type `J`. `J` must implement `serde::Deserialize` and `schemars::JsonSchema`. @@ -340,6 +341,15 @@ //! hope is that this would generally not be needed. It can be useful to //! implement functionality not provided by Dropshot. //! +//! Generally, the type parameter for the `Query`, `Header`, and `Path` extractors +//! should be Rust structs. The struct's field _names_ correspond to the keys in +//! the thing being extracted (i.e., they correspond to qquery parameter names +//! for `Query`, header names for `Header`, and path component names for `Path`). +//! The struct's field _values_ should generally be Rust primitives, strings, +//! or enums containing no data. +//! There is no facility for automatically parsing the values _again_ (e.g., +//! as JSON), which means nested values or enums with data cannot be supported. +//! //! `Query` and `Path` impl `SharedExtractor`. `TypedBody`, `UntypedBody`, //! `StreamingBody`, and `RawRequest` impl `ExclusiveExtractor`. Your function //! may accept 0-5 extractors, but only one can be `ExclusiveExtractor`, and it From f5f2d4dae6d580c60741adca6f91965970783bfe Mon Sep 17 00:00:00 2001 From: David Pacheco Date: Fri, 19 Sep 2025 15:39:16 -0700 Subject: [PATCH 3/4] fix typo --- dropshot/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dropshot/src/lib.rs b/dropshot/src/lib.rs index c8addfe13..2dba5b502 100644 --- a/dropshot/src/lib.rs +++ b/dropshot/src/lib.rs @@ -343,7 +343,7 @@ //! //! Generally, the type parameter for the `Query`, `Header`, and `Path` extractors //! should be Rust structs. The struct's field _names_ correspond to the keys in -//! the thing being extracted (i.e., they correspond to qquery parameter names +//! the thing being extracted (i.e., they correspond to query parameter names //! for `Query`, header names for `Header`, and path component names for `Path`). //! The struct's field _values_ should generally be Rust primitives, strings, //! or enums containing no data. From 4558ef046df02764c2ae224bf3452325730100ff Mon Sep 17 00:00:00 2001 From: David Pacheco Date: Fri, 19 Sep 2025 15:40:32 -0700 Subject: [PATCH 4/4] rustfmt --- dropshot/src/extractor/path.rs | 6 +++--- dropshot/src/extractor/query.rs | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dropshot/src/extractor/path.rs b/dropshot/src/extractor/path.rs index acff04e20..362eb7ae6 100644 --- a/dropshot/src/extractor/path.rs +++ b/dropshot/src/extractor/path.rs @@ -16,9 +16,9 @@ use schemars::JsonSchema; use serde::de::DeserializeOwned; use std::fmt::Debug; -/// `Path` is an extractor used to deserialize an instance of -/// `PathType` from an HTTP request's path parameters. `PathType` may be any -/// struct of yours that implements [serde::Deserialize] and +/// `Path` is an extractor used to deserialize an instance of +/// `PathType` from an HTTP request's path parameters. `PathType` may be any +/// struct of yours that implements [serde::Deserialize] and /// [schemars::JsonSchema]. /// See the top-level crate documentation for more information. #[derive(Debug)] diff --git a/dropshot/src/extractor/query.rs b/dropshot/src/extractor/query.rs index 939764094..8209a139a 100644 --- a/dropshot/src/extractor/query.rs +++ b/dropshot/src/extractor/query.rs @@ -18,7 +18,7 @@ use std::fmt::Debug; /// `Query` is an extractor used to deserialize an instance of /// `QueryType` from an HTTP request's query string. `QueryType` may be any -/// struct of yours that implements [serde::Deserialize] and +/// struct of yours that implements [serde::Deserialize] and /// [schemars::JsonSchema]. /// See the top-level crate documentation for more information. #[derive(Debug)]