roas 0.14.0

Rust OpenAPI Specification — parser, validator, and loader for OpenAPI v2.0 / v3.0.x / v3.1.x / v3.2.x
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

//! Request Body Object

use crate::v3_0::media_type::MediaType;
use crate::v3_0::spec::Spec;
use crate::validation::{Context, ValidateWithContext};
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// Describes a single request body.
///
/// Specification example:
/// ```yaml
/// description: user to add to the system
/// content:
///   'application/json':
///     schema:
///       $ref: '#/components/schemas/User'
///     examples:
///       user:
///         summary: User Example
///         externalValue: 'https://foo.bar/examples/user-example.json'
///   'application/xml':
///     schema:
///       $ref: '#/components/schemas/User'
///     examples:
///       user:
///         summary: User Example in XML
///         externalValue: 'https://foo.bar/examples/user-example.xml'
///   'text/plain':
///     examples:
///       user:
///         summary: User example in text plain format
///         externalValue: 'https://foo.bar/examples/user-example.txt'
///   '*/*':
///     examples:
///       user:
///         summary: User example in other format
///         externalValue: 'https://foo.bar/examples/user-example.whatever'
/// ```
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Default)]
pub struct RequestBody {
    /// A brief description of the parameter.
    /// This could contain examples of use.
    /// [CommonMark](https://spec.commonmark.org) syntax MAY be used for rich text representation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// **Required** The content of the request body.
    /// The key is a media type or media type range and the value describes it.
    /// For requests that match multiple keys, only the most specific key is applicable.
    /// e.g. `text/plain` overrides `text/*`
    pub content: BTreeMap<String, MediaType>,

    /// Determines if the request body is required in the request.
    /// Defaults to `false`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub required: Option<bool>,

    /// This object MAY be extended with Specification Extensions.
    /// The field name MUST begin with `x-`, for example, `x-internal-id`.
    /// The value can be null, a primitive, an array or an object.
    #[serde(flatten)]
    #[serde(with = "crate::common::extensions")]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub extensions: Option<BTreeMap<String, serde_json::Value>>,
}

impl ValidateWithContext<Spec> for RequestBody {
    fn validate_with_context(&self, ctx: &mut Context<Spec>, path: String) {
        for (k, v) in &self.content {
            v.validate_with_context(ctx, format!("{path}.content[{k}]"));
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::validation::Context;
    use crate::validation::Options;
    use serde_json::json;

    #[test]
    fn round_trip_with_extensions() {
        let v = json!({
            "description": "A user",
            "required": true,
            "content": {
                "application/json": {"schema": {"type": "object"}}
            },
            "x-internal": "yes"
        });
        let rb: RequestBody = serde_json::from_value(v.clone()).unwrap();
        assert_eq!(rb.required, Some(true));
        assert!(rb.extensions.is_some());
        assert_eq!(serde_json::to_value(&rb).unwrap(), v);
    }

    #[test]
    fn validate_walks_content() {
        let mut content = BTreeMap::new();
        content.insert(
            "application/json".to_owned(),
            crate::v3_0::media_type::MediaType {
                example: Some(json!(1)),
                examples: Some(BTreeMap::from([(
                    "a".into(),
                    crate::common::reference::RefOr::new_item(
                        crate::v3_0::example::Example::default(),
                    ),
                )])),
                ..Default::default()
            },
        );
        let rb = RequestBody {
            description: None,
            content,
            required: None,
            extensions: None,
        };
        let spec = Spec::default();
        let mut ctx = Context::new(&spec, Options::new());
        rb.validate_with_context(&mut ctx, "rb".into());
        assert!(
            ctx.errors
                .iter()
                .any(|e| e.contains("rb.content[application/json]")),
            "expected nested content error: {:?}",
            ctx.errors
        );
    }
}