Add support for tags

[pureions]

To categorize channels, servers, operations, etc. asyncapi allows to set tags to these parts of the asyncapi document. To reuse tags, tag objects can be defined in the component section and referenced in channels, servers, operations etc.
Would be great if this crate add models and derive logic to support this feature.

[mlilback]

Sketching a syntax design here before anyone starts on it. This is a proposal — pushback welcome, particularly on the two open questions at the bottom.

Design principle

Tags in AsyncAPI 3.0 attach to five things (info, server, channel, operation, message) and can also be defined once in components.tags and referenced by $ref. Since reuse is the main ask in this issue, the design leans on it: define a tag once, reference it by name everywhere else.

That keeps the parser at the five use sites trivial (a list of strings) and confines all object parsing to a single new attribute.

Proposed syntax

Defining tags — new #[asyncapi_tag(...)] on the API struct

#[derive(AsyncApi)]
#[asyncapi(title = "Chat WebSocket API", version = "1.0.0", tags = ["public"])]
#[asyncapi_tag(name = "public", description = "Stable, publicly documented surface")]
#[asyncapi_tag(name = "chat", description = "Chat room messaging")]
#[asyncapi_tag(name = "admin", description = "Requires elevated privileges")]
#[asyncapi_server(
    name = "production",
    host = "api.example.com",
    protocol = "wss",
    tags = ["public"]
)]
#[asyncapi_channel(name = "chat", address = "/ws/chat", tags = ["chat"])]
#[asyncapi_operation(
    name = "sendChatMessage",
    action = "send",
    channel = "chat",
    tags = ["chat", "public"]
)]
struct ChatApi;

Each #[asyncapi_tag(...)] becomes one entry in components.tags. This follows the existing repeated-attribute pattern already used by #[asyncapi_server] and #[asyncapi_channel].

Referencing tags — tags = [...] everywhere else

A plain list of strings on #[asyncapi], #[asyncapi_server], #[asyncapi_channel], and #[asyncapi_operation].

Message-level tags — existing #[asyncapi(...)] on the message type/variant

#[derive(Serialize, Deserialize, JsonSchema, ToAsyncApiMessage)]
#[serde(tag = "type")]
pub enum ChatMessage {
    #[serde(rename = "user.join")]
    #[asyncapi(summary = "User joins", tags = ["chat"])]
    UserJoin { username: String, room: String },
}

Note this is a second parsing path — ToAsyncApiMessage has its own AsyncApiMeta in asyncapi_attrs.rs, separate from asyncapi_spec_attrs.rs. Message tags reference the same components.tags names, which means the message macro can't validate them (it doesn't see the API struct); validation there would have to be deferred to the AsyncApi derive or skipped.

Model changes

Mirroring the existing MessageRef, which already models the $ref-or-inline pattern:

pub struct Tag {
    pub name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum TagRef {
    Reference {
        #[serde(rename = "$ref")]
        reference: String,
    },
    Inline(Tag),
}

Plus tags: Option<Vec<TagRef>> on Info, Server, Channel, Operation, Message, and tags: Option<IndexMap<String, Tag>> on Components.

Generated output

{
  "channels": {
    "chat": {
      "address": "/ws/chat",
      "tags": [{ "$ref": "#/components/tags/chat" }]
    }
  },
  "components": {
    "tags": {
      "chat": { "name": "chat", "description": "Chat room messaging" },
      "public": { "name": "public", "description": "Stable, publicly documented surface" }
    }
  }
}

Validation

Referencing an undeclared tag name should be a compile error pointing at the offending attribute:

error: unknown tag "chatt"; declare it with #[asyncapi_tag(name = "chatt", ...)]

This is worth insisting on. We currently have a related class of bug in the operation/channel message refs (see #17), where refs are emitted into a components section that may not exist, producing a silently invalid spec with no diagnostic. Tags should not repeat that.

TagRef::Inline exists in the model so hand-built specs can use it, but the derive macro would only ever emit Reference.

Open questions

1. externalDocs on Tag — the spec allows it, but there's no ExternalDocumentation model in the crate at all, and it'd also be wanted on info, operation, etc. I'd leave it out of this issue and file it separately rather than let it expand scope here.
2. Is info.tags worth supporting? It's in the spec and nearly free once the rest exists, but tagging the document as a whole is of limited use. Easy to include; just flagging it.
3. Should an undeclared tag name emit an inline {"name": "x"} instead of erroring? More forgiving, and saves a line for one-off tags — but it silently loses the typo protection above. My inclination is no.

Sequencing

This touches the same channel/operation codegen paths that #17 rewrites, so it's worth landing #17 first rather than resolving that conflict twice.