utoipa/openapi/
header.rs

1//! Implements [OpenAPI Header Object][header] types.
2//!
3//! [header]: https://spec.openapis.org/oas/latest.html#header-object
4
5use serde::{Deserialize, Serialize};
6
7use super::{builder, set_value, Object, RefOr, Schema, SchemaType};
8
9builder! {
10    HeaderBuilder;
11
12    /// Implements [OpenAPI Header Object][header] for response headers.
13    ///
14    /// [header]: https://spec.openapis.org/oas/latest.html#header-object
15    #[non_exhaustive]
16    #[derive(Serialize, Deserialize, Clone, PartialEq)]
17    #[cfg_attr(feature = "debug", derive(Debug))]
18    pub struct Header {
19        /// Schema of header type.
20        pub schema: RefOr<Schema>,
21
22        /// Additional description of the header value.
23        #[serde(skip_serializing_if = "Option::is_none")]
24        pub description: Option<String>,
25    }
26}
27
28impl Header {
29    /// Construct a new [`Header`] with custom schema. If you wish to construct a default
30    /// header with `String` type you can use [`Header::default`] function.
31    ///
32    /// # Examples
33    ///
34    /// Create new [`Header`] with integer type.
35    /// ```rust
36    /// # use utoipa::openapi::header::Header;
37    /// # use utoipa::openapi::{Object, SchemaType};
38    /// let header = Header::new(Object::with_type(SchemaType::Integer));
39    /// ```
40    ///
41    /// Create a new [`Header`] with default type `String`
42    /// ```rust
43    /// # use utoipa::openapi::header::Header;
44    /// let header = Header::default();
45    /// ```
46    pub fn new<C: Into<RefOr<Schema>>>(component: C) -> Self {
47        Self {
48            schema: component.into(),
49            ..Default::default()
50        }
51    }
52}
53
54impl Default for Header {
55    fn default() -> Self {
56        Self {
57            description: Default::default(),
58            schema: Object::with_type(SchemaType::String).into(),
59        }
60    }
61}
62
63impl HeaderBuilder {
64    /// Add schema of header.
65    pub fn schema<I: Into<RefOr<Schema>>>(mut self, component: I) -> Self {
66        set_value!(self schema component.into())
67    }
68
69    /// Add additional description for header.
70    pub fn description<S: Into<String>>(mut self, description: Option<S>) -> Self {
71        set_value!(self description description.map(|description| description.into()))
72    }
73}
utoipa/openapi/header.rs

utoipa/openapi/
header.rs
