kynos_openapi/model/
tag.rs

1//! The Tag Object.
2
3use serde::{Deserialize, Serialize};
4
5use crate::model::{extensions::Extensions, external_docs::ExternalDocumentation};
6
7/// Metadata for a single tag used by [`Operation::tags`](crate::Operation::tags).
8///
9/// Tag names must be unique across a document. In Kynos a tag is a *type*
10/// rather than a string, so uniqueness is a property of the type system rather
11/// than something checked after the fact.
12#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
13pub struct Tag {
14    /// The name of the tag. Operations refer to it by this value.
15    pub name: String,
16
17    /// A short summary of the tag.
18    ///
19    /// Introduced in OpenAPI 3.2.
20    #[cfg(feature = "openapi32")]
21    #[serde(default, skip_serializing_if = "Option::is_none")]
22    pub summary: Option<String>,
23
24    /// A description for the tag. [CommonMark] syntax may be used.
25    ///
26    /// [CommonMark]: https://spec.commonmark.org/
27    #[serde(default, skip_serializing_if = "Option::is_none")]
28    pub description: Option<String>,
29
30    /// The [`name`](Tag::name) of a tag that this tag nests under.
31    ///
32    /// Introduced in OpenAPI 3.2. The named tag must exist, and the parent
33    /// chain must not contain a cycle; [`crate::validate`] checks both.
34    #[cfg(feature = "openapi32")]
35    #[serde(default, skip_serializing_if = "Option::is_none")]
36    pub parent: Option<String>,
37
38    /// A machine-readable categorization of what sort of tag this is.
39    ///
40    /// Introduced in OpenAPI 3.2. Any string is permitted; `nav`, `badge` and
41    /// `audience` are the common registered values.
42    #[cfg(feature = "openapi32")]
43    #[serde(default, skip_serializing_if = "Option::is_none")]
44    pub kind: Option<String>,
45
46    /// Additional external documentation for this tag.
47    #[serde(
48        rename = "externalDocs",
49        default,
50        skip_serializing_if = "Option::is_none"
51    )]
52    pub external_docs: Option<ExternalDocumentation>,
53
54    /// Specification extensions.
55    #[serde(flatten)]
56    pub extensions: Extensions,
57}
58
59impl Tag {
60    /// Creates a tag with the given name.
61    pub fn new(name: impl Into<String>) -> Self {
62        Self {
63            name: name.into(),
64            ..Self::default()
65        }
66    }
67
68    /// Sets the description.
69    #[must_use]
70    pub fn with_description(mut self, description: impl Into<String>) -> Self {
71        self.description = Some(description.into());
72        self
73    }
74
75    /// Nests this tag under another.
76    ///
77    /// Introduced in OpenAPI 3.2.
78    #[cfg(feature = "openapi32")]
79    #[must_use]
80    pub fn with_parent(mut self, parent: impl Into<String>) -> Self {
81        self.parent = Some(parent.into());
82        self
83    }
84
85    /// Sets the machine-readable tag category.
86    ///
87    /// Introduced in OpenAPI 3.2.
88    #[cfg(feature = "openapi32")]
89    #[must_use]
90    pub fn with_kind(mut self, kind: impl Into<String>) -> Self {
91        self.kind = Some(kind.into());
92        self
93    }
94}
kynos_openapi/model/tag.rs

kynos_openapi/model/
tag.rs
