salvo_oapi/openapi/
external_docs.rs

1//! Implements [OpenAPI External Docs Object][external_docs] types.
2//!
3//! [external_docs]: https://spec.openapis.org/oas/latest.html#xml-object
4use serde::{Deserialize, Serialize};
5
6/// Reference of external resource allowing extended documentation.
7#[non_exhaustive]
8#[derive(Serialize, Deserialize, Default, Clone, Debug, PartialEq, Eq)]
9#[serde(rename_all = "camelCase")]
10pub struct ExternalDocs {
11    /// Target url for external documentation location.
12    pub url: String,
13    /// Additional description supporting markdown syntax of the external documentation.
14    pub description: Option<String>,
15}
16
17impl ExternalDocs {
18    /// Construct a new [`ExternalDocs`].
19    ///
20    /// Function takes target url argument for the external documentation location.
21    ///
22    /// # Examples
23    ///
24    /// ```
25    /// # use salvo_oapi::ExternalDocs;
26    /// let external_docs = ExternalDocs::new("https://pet-api.external.docs");
27    /// ```
28    pub fn new<S: AsRef<str>>(url: S) -> Self {
29        Self {
30            url: url.as_ref().to_string(),
31            ..Default::default()
32        }
33    }
34
35    /// Add target url for external documentation location.
36    pub fn url<I: Into<String>>(mut self, url: I) -> Self {
37        self.url = url.into();
38        self
39    }
40
41    /// Add additional description of external documentation.
42    pub fn description<S: Into<String>>(mut self, description: S) -> Self {
43        self.description = Some(description.into());
44        self
45    }
46}
47
48#[cfg(test)]
49mod tests {
50    use super::*;
51
52    #[test]
53    fn test_default_external_docs() {
54        let external_docs = ExternalDocs::default();
55        assert_eq!(external_docs.url, "");
56        assert_eq!(external_docs.description, None);
57    }
58
59    #[test]
60    fn test_build_external_docs() {
61        let external_docs = ExternalDocs::default();
62        let external_docs_with_url = external_docs
63            .url("https://pet-api.external.docs")
64            .description("description");
65
66        assert_eq!(external_docs_with_url.url, "https://pet-api.external.docs");
67        assert_eq!(
68            external_docs_with_url.description,
69            Some("description".to_string())
70        );
71    }
72}
salvo_oapi/openapi/external_docs.rs

salvo_oapi/openapi/
external_docs.rs
