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        /// 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        /// Optional extensions "x-something".
33        #[serde(skip_serializing_if = "Option::is_none", flatten)]
34        pub extensions: Option<Extensions>,
35    }
36}
37
38impl Tag {
39    /// Construct a new [`Tag`] with given name.
40    pub fn new<S: AsRef<str>>(name: S) -> Self {
41        Self {
42            name: name.as_ref().to_string(),
43            ..Default::default()
44        }
45    }
46}
47
48impl TagBuilder {
49    /// Add name of the tag.
50    pub fn name<I: Into<String>>(mut self, name: I) -> Self {
51        set_value!(self name name.into())
52    }
53
54    /// Add additional description for the tag.
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 additional external documentation for the tag.
60    pub fn external_docs(mut self, external_docs: Option<ExternalDocs>) -> Self {
61        set_value!(self external_docs external_docs)
62    }
63
64    /// Add openapi extensions (x-something) to the tag.
65    pub fn extensions(mut self, extensions: Option<Extensions>) -> Self {
66        set_value!(self extensions extensions)
67    }
68}
utoipa/openapi/tag.rs

utoipa/openapi/
tag.rs
