fix: keep non-local 2.x channel server references intact

Only a local "#/servers/{name}" reference is reduced to a server name. An
external reference, or any other pointer, is written as is, since reducing it
to its last token would silently point the channel at a local server of the
same name. The name is decoded as one token, so both the 2.x reader's
unescaped form and an escaped 3.x pointer give the same name.

Also adds 3.x channel server tests, so the change is shown not to regress
3.x serialization or the 2.x to 3.x upgrade.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI/Models/AsyncApiChannel.cs

@@ -168,18 +168,20 @@ private bool CheckOperationChannel(AsyncApiOperation operation, IAsyncApiWriter
         }
 
         /// <summary>
-        /// AsyncAPI 2.x lists channel servers by name, so a "#/servers/{name}" pointer is written as "{name}".
+        /// AsyncAPI 2.x lists channel servers by name, so a local "#/servers/{name}" pointer is written as "{name}".
+        /// Any other reference is written as is, since reducing it to a name would point it at a local server instead.
         /// </summary>
         private static string GetV2ServerName(AsyncApiServerReference server)
         {
-            var fragmentId = server.Reference.FragmentId;
-            if (fragmentId == null)
+            const string serversPrefix = "/" + AsyncApiConstants.Servers + "/";
+            var reference = server.Reference;
+            if (reference.IsExternal || reference.FragmentId?.StartsWith(serversPrefix) != true)
             {
-                return server.Reference.Reference;
+                return reference.Reference;
             }
 
-            var tokens = new JsonPointer(fragmentId).Tokens;
-            return tokens.Length == 2 && tokens[0] == AsyncApiConstants.Servers ? tokens[1] : fragmentId;
+            // The 2.x reader keeps the name unescaped, while a 3.x pointer escapes it, so decode the whole remainder as one token.
+            return reference.FragmentId.Substring(serversPrefix.Length).Replace("~1", "/").Replace("~0", "~");
         }
     }
 }

test/ByteBard.AsyncAPI.Tests/Models/AsyncApiChannel_Should.cs

@@ -203,6 +203,99 @@ public void V2_AsyncApiChannel_WithServerReference_SerializesServerName()
             actual.Should().BePlatformAgnosticEquivalentTo(expected);
         }
 
+        [TestCase("#/servers/east~1west", "east/west")]
+        [TestCase("#/servers/a~0b", "a~b")]
+        [TestCase("other.yaml#/servers/production", "other.yaml#/servers/production")]
+        [TestCase("#/components/servers/production", "'#/components/servers/production'")]
+        public void V2_AsyncApiChannel_WithServerReference_SerializesServerNameOnlyForLocalServer(string reference, string expectedServer)
+        {
+            var channel = new AsyncApiChannel
+            {
+                Servers = new List<AsyncApiServerReference> { new AsyncApiServerReference(reference) },
+            };
+
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0);
+
+            actual.Should().BePlatformAgnosticEquivalentTo($"servers:\n  - {expectedServer}");
+        }
+
+        [Test]
+        public void V3_AsyncApiChannel_WithServers_Reserializes()
+        {
+            var yaml =
+                """
+                asyncapi: 3.1.0
+                info:
+                  title: test spec
+                  version: 1.0.0
+                servers:
+                  production:
+                    host: example.com
+                    protocol: kafka
+                channels:
+                  mychannel:
+                    servers:
+                      - $ref: '#/servers/production'
+                components: { }
+                """;
+
+            var document = new AsyncApiStringReader().Read(yaml, out var diag);
+
+            diag.Errors.Should().BeEmpty();
+            var server = document.Channels.First().Value.Servers.Single();
+            server.Reference.Reference.Should().Be("#/servers/production");
+            server.Host.Should().Be("example.com");
+
+            var reserialized = document.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            reserialized.Should().BePlatformAgnosticEquivalentTo(yaml);
+        }
+
+        [Test]
+        public void V3_AsyncApiChannel_WithServerReference_SerializesReference()
+        {
+            var expected =
+                """
+                servers:
+                  - $ref: '#/servers/production'
+                """;
+
+            var channel = new AsyncApiChannel
+            {
+                Servers = new List<AsyncApiServerReference> { new AsyncApiServerReference("#/servers/production") },
+            };
+
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            actual.Should().BePlatformAgnosticEquivalentTo(expected);
+        }
+
+        [Test]
+        public void V2_AsyncApiChannel_WithServers_UpgradesToV3References()
+        {
+            var yaml =
+                """
+                asyncapi: 2.6.0
+                info:
+                  title: test spec
+                  version: 1.0.0
+                servers:
+                  production:
+                    url: example.com
+                    protocol: kafka
+                channels:
+                  mychannel:
+                    servers:
+                      - production
+                """;
+
+            var document = new AsyncApiStringReader().Read(yaml, out var diag);
+
+            var reserialized = document.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            reserialized.Should().Contain("- $ref: '#/servers/production'");
+        }
+
         [Test]
         public void V2_AsyncApiChannel_reserializes()
         {