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    #[must_use]
29    pub fn new<S: AsRef<str>>(url: S) -> Self {
30        Self {
31            url: url.as_ref().to_owned(),
32            ..Default::default()
33        }
34    }
35
36    /// Add target url for external documentation location.
37    #[must_use]
38    pub fn url<I: Into<String>>(mut self, url: I) -> Self {
39        self.url = url.into();
40        self
41    }
42
43    /// Add additional description of external documentation.
44    #[must_use]
45    pub fn description<S: Into<String>>(mut self, description: S) -> Self {
46        self.description = Some(description.into());
47        self
48    }
49}
50
51#[cfg(test)]
52mod tests {
53    use super::*;
54
55    #[test]
56    fn test_default_external_docs() {
57        let external_docs = ExternalDocs::default();
58        assert_eq!(external_docs.url, "");
59        assert_eq!(external_docs.description, None);
60    }
61
62    #[test]
63    fn test_build_external_docs() {
64        let external_docs = ExternalDocs::default();
65        let external_docs_with_url = external_docs
66            .url("https://pet-api.external.docs")
67            .description("description");
68
69        assert_eq!(external_docs_with_url.url, "https://pet-api.external.docs");
70        assert_eq!(
71            external_docs_with_url.description,
72            Some("description".to_owned())
73        );
74    }
75}
salvo_oapi/openapi/external_docs.rs

salvo_oapi/openapi/
external_docs.rs
