utoipa/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
6use super::extensions::Extensions;
7use super::{builder, set_value};
8
9builder! {
10    ExternalDocsBuilder;
11
12    /// Reference of external resource allowing extended documentation.
13    #[non_exhaustive]
14    #[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
15    #[cfg_attr(feature = "debug", derive(Debug))]
16    #[serde(rename_all = "camelCase")]
17    pub struct ExternalDocs {
18        /// Target url for external documentation location.
19        pub url: String,
20        /// Additional description supporting markdown syntax of the external documentation.
21        pub description: Option<String>,
22
23        /// Optional extensions "x-something".
24        #[serde(skip_serializing_if = "Option::is_none", flatten)]
25        pub extensions: Option<Extensions>,
26    }
27}
28
29impl ExternalDocs {
30    /// Construct a new [`ExternalDocs`].
31    ///
32    /// Function takes target url argument for the external documentation location.
33    ///
34    /// # Examples
35    ///
36    /// ```rust
37    /// # use utoipa::openapi::external_docs::ExternalDocs;
38    /// let external_docs = ExternalDocs::new("https://pet-api.external.docs");
39    /// ```
40    pub fn new<S: AsRef<str>>(url: S) -> Self {
41        Self {
42            url: url.as_ref().to_string(),
43            ..Default::default()
44        }
45    }
46}
47
48impl ExternalDocsBuilder {
49    /// Add target url for external documentation location.
50    pub fn url<I: Into<String>>(mut self, url: I) -> Self {
51        set_value!(self url url.into())
52    }
53
54    /// Add additional description of external documentation.
55    pub fn description<S: Into<String>>(mut self, description: Option<S>) -> Self {
56        set_value!(self description description.map(|description| description.into()))
57    }
58
59    /// Add openapi extensions (x-something) of the API.
60    pub fn extensions(mut self, extensions: Option<Extensions>) -> Self {
61        set_value!(self extensions extensions)
62    }
63}
utoipa/openapi/external_docs.rs

utoipa/openapi/
external_docs.rs
