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, extensions::Extensions, 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        /// Short summary for the tag.
25        #[serde(skip_serializing_if = "Option::is_none")]
26        pub summary: Option<String>,
27
28        /// Additional description for the tag shown in the document.
29        #[serde(skip_serializing_if = "Option::is_none")]
30        pub description: Option<String>,
31
32        /// Name of this tag's parent tag.
33        #[serde(skip_serializing_if = "Option::is_none")]
34        pub parent: Option<String>,
35
36        /// Kind of tag, allowing tooling to distinguish grouping tags from other tag purposes.
37        #[serde(skip_serializing_if = "Option::is_none")]
38        pub kind: Option<String>,
39
40        /// Additional external documentation for the tag.
41        #[serde(skip_serializing_if = "Option::is_none")]
42        pub external_docs: Option<ExternalDocs>,
43
44        /// Optional extensions "x-something".
45        #[serde(skip_serializing_if = "Option::is_none", flatten)]
46        pub extensions: Option<Extensions>,
47    }
48}
49
50impl Tag {
51    /// Construct a new [`Tag`] with given name.
52    pub fn new<S: AsRef<str>>(name: S) -> Self {
53        Self {
54            name: name.as_ref().to_string(),
55            ..Default::default()
56        }
57    }
58}
59
60impl TagBuilder {
61    /// Add name of the tag.
62    pub fn name<I: Into<String>>(mut self, name: I) -> Self {
63        set_value!(self name name.into())
64    }
65
66    /// Add short summary for the tag.
67    pub fn summary<S: Into<String>>(mut self, summary: Option<S>) -> Self {
68        set_value!(self summary summary.map(|summary| summary.into()))
69    }
70
71    /// Add additional description for the tag.
72    pub fn description<S: Into<String>>(mut self, description: Option<S>) -> Self {
73        set_value!(self description description.map(|description| description.into()))
74    }
75
76    /// Add parent tag name.
77    pub fn parent<S: Into<String>>(mut self, parent: Option<S>) -> Self {
78        set_value!(self parent parent.map(|parent| parent.into()))
79    }
80
81    /// Add tag kind.
82    pub fn kind<S: Into<String>>(mut self, kind: Option<S>) -> Self {
83        set_value!(self kind kind.map(|kind| kind.into()))
84    }
85
86    /// Add additional external documentation for the tag.
87    pub fn external_docs(mut self, external_docs: Option<ExternalDocs>) -> Self {
88        set_value!(self external_docs external_docs)
89    }
90
91    /// Add openapi extensions (x-something) to the tag.
92    pub fn extensions(mut self, extensions: Option<Extensions>) -> Self {
93        set_value!(self extensions extensions)
94    }
95}
utoipa/openapi/tag.rs

utoipa/openapi/
tag.rs
