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

utoipa/openapi/
external_docs.rs
