salvo_oapi/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::{BasicType, Object, RefOr, Schema};
8
9/// Implements [OpenAPI Header Object][header] for response headers.
10///
11/// [header]: https://spec.openapis.org/oas/latest.html#header-object
12#[non_exhaustive]
13#[derive(Serialize, Deserialize, Clone, Debug, PartialEq)]
14pub struct Header {
15    /// Schema of header type.
16    pub schema: RefOr<Schema>,
17
18    /// Additional description of the header value.
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub description: Option<String>,
21}
22
23impl Header {
24    /// Construct a new [`Header`] with custom schema. If you wish to construct a default
25    /// header with `String` type you can use [`Header::default`] function.
26    ///
27    /// # Examples
28    ///
29    /// Create new [`Header`] with integer type.
30    /// ```
31    /// # use salvo_oapi::{Header, Object, BasicType};
32    /// let header = Header::new(Object::with_type(BasicType::Integer));
33    /// ```
34    ///
35    /// Create a new [`Header`] with default type `String`
36    /// ```
37    /// # use salvo_oapi::Header;
38    /// let header = Header::default();
39    /// ```
40    #[must_use]
41    pub fn new<C: Into<RefOr<Schema>>>(component: C) -> Self {
42        Self {
43            schema: component.into(),
44            ..Default::default()
45        }
46    }
47    /// Add schema of header.
48    #[must_use]
49    pub fn schema<I: Into<RefOr<Schema>>>(mut self, component: I) -> Self {
50        self.schema = component.into();
51        self
52    }
53
54    /// Add additional description for header.
55    #[must_use]
56    pub fn description<S: Into<String>>(mut self, description: S) -> Self {
57        self.description = Some(description.into());
58        self
59    }
60}
61
62impl Default for Header {
63    fn default() -> Self {
64        Self {
65            description: Default::default(),
66            schema: Object::with_type(BasicType::String).into(),
67        }
68    }
69}
70
71#[cfg(test)]
72mod tests {
73    use assert_json_diff::assert_json_eq;
74    use serde_json::json;
75
76    use super::*;
77
78    #[test]
79    fn test_build_header() {
80        let header = Header::new(Object::with_type(BasicType::String));
81        assert_json_eq!(
82            header,
83            json!({
84                "schema": {
85                    "type": "string"
86                }
87            })
88        );
89
90        let header = header
91            .description("test description")
92            .schema(Object::with_type(BasicType::Number));
93        assert_json_eq!(
94            header,
95            json!({
96                "description": "test description",
97                "schema": {
98                    "type": "number"
99                }
100            })
101        );
102    }
103}
salvo_oapi/openapi/header.rs

salvo_oapi/openapi/
header.rs
