utoipa/openapi/
tag.rs

1//! Implements [OpenAPI Tag Object][tag] types.
2//!
3//! [tag]: https://spec.openapis.org/oas/latest.html#tag-object
4use serde::{Deserialize, Serialize};
5
6use super::{builder, external_docs::ExternalDocs, set_value};
7
8builder! {
9    TagBuilder;
10
11    /// Implements [OpenAPI Tag Object][tag].
12    ///
13    /// Tag can be used to provide additional metadata for tags used by path operations.
14    ///
15    /// [tag]: https://spec.openapis.org/oas/latest.html#tag-object
16    #[non_exhaustive]
17    #[derive(Serialize, Deserialize, Default, Clone, PartialEq, Eq)]
18    #[cfg_attr(feature = "debug", derive(Debug))]
19    #[serde(rename_all = "camelCase")]
20    pub struct Tag {
21        /// Name of the tag. Should match to tag of **operation**.
22        pub name: String,
23
24        /// Additional description for the tag shown in the document.
25        #[serde(skip_serializing_if = "Option::is_none")]
26        pub description: Option<String>,
27
28        /// Additional external documentation for the tag.
29        #[serde(skip_serializing_if = "Option::is_none")]
30        pub external_docs: Option<ExternalDocs>,
31    }
32}
33
34impl Tag {
35    /// Construct a new [`Tag`] with given name.
36    pub fn new<S: AsRef<str>>(name: S) -> Self {
37        Self {
38            name: name.as_ref().to_string(),
39            ..Default::default()
40        }
41    }
42}
43
44impl TagBuilder {
45    /// Add name fo the tag.
46    pub fn name<I: Into<String>>(mut self, name: I) -> Self {
47        set_value!(self name name.into())
48    }
49
50    /// Add additional description for the tag.
51    pub fn description<S: Into<String>>(mut self, description: Option<S>) -> Self {
52        set_value!(self description description.map(|description| description.into()))
53    }
54
55    /// Add additional external documentation for the tag.
56    pub fn external_docs(mut self, external_docs: Option<ExternalDocs>) -> Self {
57        set_value!(self external_docs external_docs)
58    }
59}
utoipa/openapi/tag.rs

utoipa/openapi/
tag.rs
