Fix OpenAPI XML code gen (#60977)

Author: captainsafia

src/OpenApi/gen/Helpers/ISymbolExtensions.cs

@@ -189,4 +189,26 @@ public static IEnumerable<INamedTypeSymbol> GetBaseTypes(this ITypeSymbol? type)
             current = current.BaseType;
         }
     }
+
+    public static bool IsAccessibleType(this ISymbol symbol)
+    {
+        // Check if the symbol itself is public
+        if (symbol.DeclaredAccessibility != Accessibility.Public)
+        {
+            return false;
+        }
+
+        // Check if all containing types are public as well
+        var containingType = symbol.ContainingType;
+        while (containingType != null)
+        {
+            if (containingType.DeclaredAccessibility != Accessibility.Public)
+            {
+                return false;
+            }
+            containingType = containingType.ContainingType;
+        }
+
+        return true;
+    }
 }

src/OpenApi/gen/XmlCommentGenerator.Emitter.cs

@@ -27,6 +27,9 @@ internal static string GenerateXmlCommentSupportSource(string commentsFromXmlFil
 // </auto-generated>
 //------------------------------------------------------------------------------
 #nullable enable
+// Suppress warnings about obsolete types and members
+// in generated code
+#pragma warning disable CS0612, CS0618
 
 namespace System.Runtime.CompilerServices
 {
@@ -487,7 +490,7 @@ internal static string EmitSourceGeneratedXmlComment(XmlComment comment)
         else
         {
             codeWriter.Write("[");
-            for (int i = 0; i < comment.Examples.Count; i++)
+            for (var i = 0; i < comment.Examples.Count; i++)
             {
                 var example = comment.Examples[i];
                 codeWriter.Write(FormatStringForCode(example));
@@ -506,13 +509,18 @@ internal static string EmitSourceGeneratedXmlComment(XmlComment comment)
         else
         {
             codeWriter.Write("[");
-            for (int i = 0; i < comment.Parameters.Count; i++)
+            for (var i = 0; i < comment.Parameters.Count; i++)
             {
                 var parameter = comment.Parameters[i];
                 var exampleLiteral = string.IsNullOrEmpty(parameter.Example)
                     ? "null"
                     : FormatStringForCode(parameter.Example!);
-                codeWriter.Write($"new XmlParameterComment(@\"{parameter.Name}\", @\"{parameter.Description}\", {exampleLiteral}, {(parameter.Deprecated == true ? "true" : "false")})");
+                codeWriter.Write("new XmlParameterComment(");
+                codeWriter.Write(FormatStringForCode(parameter.Name) + ", ");
+                codeWriter.Write(FormatStringForCode(parameter.Description) + ", ");
+                codeWriter.Write(exampleLiteral + ", ");
+                codeWriter.Write(parameter.Deprecated == true ? "true" : "false");
+                codeWriter.Write(")");
                 if (i < comment.Parameters.Count - 1)
                 {
                     codeWriter.Write(", ");
@@ -528,10 +536,13 @@ internal static string EmitSourceGeneratedXmlComment(XmlComment comment)
         else
         {
             codeWriter.Write("[");
-            for (int i = 0; i < comment.Responses.Count; i++)
+            for (var i = 0; i < comment.Responses.Count; i++)
             {
                 var response = comment.Responses[i];
-                codeWriter.Write($"new XmlResponseComment(@\"{response.Code}\", @\"{response.Description}\", {(response.Example is null ? "null" : FormatStringForCode(response.Example))})");
+                codeWriter.Write("new XmlResponseComment(");
+                codeWriter.Write(FormatStringForCode(response.Code) + ", ");
+                codeWriter.Write(FormatStringForCode(response.Description) + ", ");
+                codeWriter.Write(response.Example is null ? "null)" : FormatStringForCode(response.Example) + ")");
                 if (i < comment.Responses.Count - 1)
                 {
                     codeWriter.Write(", ");

src/OpenApi/gen/XmlCommentGenerator.Parser.cs

@@ -91,7 +91,13 @@ public sealed partial class XmlCommentGenerator
         var comments = new List<(MemberKey, XmlComment?)>();
         foreach (var (name, value) in input.RawComments)
         {
-            if (DocumentationCommentId.GetFirstSymbolForDeclarationId(name, compilation) is ISymbol symbol)
+            if (DocumentationCommentId.GetFirstSymbolForDeclarationId(name, compilation) is ISymbol symbol &&
+                // Only include symbols that are declared in the application assembly or are
+                // accessible from the application assembly.
+                (SymbolEqualityComparer.Default.Equals(symbol.ContainingAssembly, input.Compilation.Assembly) || symbol.IsAccessibleType()) &&
+                // Skip static classes that are just containers for members with annotations
+                // since they cannot be instantiated.
+                symbol is not INamedTypeSymbol { TypeKind: TypeKind.Class, IsStatic: true })
             {
                 var parsedComment = XmlComment.Parse(symbol, compilation, value, cancellationToken);
                 if (parsedComment is not null)

src/OpenApi/gen/XmlComments/MemberKey.cs

@@ -46,7 +46,7 @@ public static MemberKey FromMethodSymbol(IMethodSymbol method, Compilation compi
 
             returnType = actualReturnType.TypeKind == TypeKind.TypeParameter
                 ? "typeof(object)"
-                : $"typeof({actualReturnType.ToDisplayString(_typeKeyFormat)})";
+                : $"typeof({ReplaceGenericArguments(actualReturnType.ToDisplayString(_typeKeyFormat))})";
         }
 
         // Handle extension methods by skipping the 'this' parameter
@@ -62,10 +62,10 @@ public static MemberKey FromMethodSymbol(IMethodSymbol method, Compilation compi
                 // For params arrays, use the array type
                 if (p.IsParams && p.Type is IArrayTypeSymbol arrayType)
                 {
-                    return $"typeof({arrayType.ToDisplayString(_typeKeyFormat)})";
+                    return $"typeof({ReplaceGenericArguments(arrayType.ToDisplayString(_typeKeyFormat))})";
                 }
 
-                return $"typeof({p.Type.ToDisplayString(_typeKeyFormat)})";
+                return $"typeof({ReplaceGenericArguments(p.Type.ToDisplayString(_typeKeyFormat))})";
             })
             .ToArray();
 

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/AdditionalTextsTests.Schemas.cs

@@ -30,6 +30,7 @@ public async Task CanHandleXmlForSchemasInAdditionalTexts()
 app.MapPost("/project-record", (ProjectRecord project) => { });
 app.MapPost("/todo-with-description", (TodoWithDescription todo) => { });
 app.MapPost("/type-with-examples", (TypeWithExamples typeWithExamples) => { });
+app.MapPost("/external-method", ClassLibrary.Endpoints.ExternalMethod);
 
 app.Run();
 """;
@@ -61,6 +62,9 @@ public class ProjectBoard
     /// </summary>
     public class BoardItem
     {
+        /// <summary>
+        /// The identifier of the board item. Defaults to "name".
+        /// </summary>
         public string Name { get; set; }
     }
 }
@@ -120,6 +124,37 @@ public class TypeWithExamples
     /// <example>https://example.com</example>
     public Uri UriType { get; set; }
 }
+
+public class Holder<T>
+{
+    /// <summary>
+    /// The value to hold.
+    /// </summary>
+    public T Value { get; set; }
+
+    public Holder(T value)
+    {
+        Value = value;
+    }
+}
+
+public static class Endpoints
+{
+    /// <summary>
+    /// An external method.
+    /// </summary>
+    /// <param name="name">The name of the tester. Defaults to "Tester".</param>
+    public static void ExternalMethod(string name = "Tester") { }
+
+    /// <summary>
+    /// Creates a holder for the specified value.
+    /// </summary>
+    /// <typeparam name="T">The type of the value.</typeparam>
+    /// <param name="value">The value to hold.</param>
+    /// <returns>A holder for the specified value.</returns>
+    /// <example>{ value: 42 }</example>
+    public static Holder<T> CreateHolder<T>(T value) => new(value);
+}
 """;
         var references = new Dictionary<string, List<string>>
         {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs

@@ -330,7 +330,7 @@ public class InheritAllButRemarks
 /// In generic classes and methods, you'll often want to reference the
 /// generic type, or the type parameter.
 /// </remarks>
-class GenericClass<T>
+public class GenericClass<T>
 {
     // Fields and members.
 }

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AddOpenApiTests.CanInterceptAddOpenApi#OpenApiXmlCommentSupport.generated.verified.cs

@@ -8,6 +8,9 @@
 // </auto-generated>
 //------------------------------------------------------------------------------
 #nullable enable
+// Suppress warnings about obsolete types and members
+// in generated code
+#pragma warning disable CS0612, CS0618
 
 namespace System.Runtime.CompilerServices
 {

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/AdditionalTextsTests.CanHandleXmlForSchemasInAdditionalTexts#OpenApiXmlCommentSupport.generated.verified.cs

@@ -8,6 +8,9 @@
 // </auto-generated>
 //------------------------------------------------------------------------------
 #nullable enable
+// Suppress warnings about obsolete types and members
+// in generated code
+#pragma warning disable CS0612, CS0618
 
 namespace System.Runtime.CompilerServices
 {
@@ -186,6 +189,7 @@ private static Dictionary<MemberKey, XmlComment> GenerateCacheEntries()
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.Project), MemberType.Type, null, null, []), new XmlComment(@"The project that contains Todo items.", null, null, null, null, false, null, null, null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.Project), MemberType.Method, ".ctor", typeof(void), [typeof(global::System.String), typeof(global::System.String)]), new XmlComment(@"The project that contains Todo items.", null, null, null, null, false, null, null, null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.ProjectBoard.BoardItem), MemberType.Type, null, null, []), new XmlComment(@"An item on the board.", null, null, null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::ClassLibrary.ProjectBoard.BoardItem), MemberType.Property, "Name", null, []), new XmlComment(@"The identifier of the board item. Defaults to ""name"".", null, null, null, null, false, null, null, null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.ProjectRecord), MemberType.Type, null, null, []), new XmlComment(@"The project that contains Todo items.", null, null, null, null, false, null, [new XmlParameterComment(@"Name", @"The name of the project.", null, false), new XmlParameterComment(@"Description", @"The description of the project.", null, false)], null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.ProjectRecord), MemberType.Method, ".ctor", typeof(void), [typeof(global::System.String), typeof(global::System.String)]), new XmlComment(@"The project that contains Todo items.", null, null, null, null, false, null, [new XmlParameterComment(@"Name", @"The name of the project.", null, false), new XmlParameterComment(@"Description", @"The description of the project.", null, false)], null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.ProjectRecord), MemberType.Property, "Name", null, []), new XmlComment(@"The name of the project.", null, null, null, null, false, null, null, null));
@@ -207,6 +211,9 @@ private static Dictionary<MemberKey, XmlComment> GenerateCacheEntries()
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.TypeWithExamples), MemberType.Property, "ByteType", null, []), new XmlComment(null, null, null, null, null, false, [@"255"], null, null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.TypeWithExamples), MemberType.Property, "DecimalType", null, []), new XmlComment(null, null, null, null, null, false, [@"3.14159265359"], null, null));
             _cache.Add(new MemberKey(typeof(global::ClassLibrary.TypeWithExamples), MemberType.Property, "UriType", null, []), new XmlComment(null, null, null, null, null, false, [@"https://example.com"], null, null));
+            _cache.Add(new MemberKey(typeof(global::ClassLibrary.Holder<>), MemberType.Property, "Value", null, []), new XmlComment(@"The value to hold.", null, null, null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::ClassLibrary.Endpoints), MemberType.Method, "ExternalMethod", typeof(void), [typeof(global::System.String)]), new XmlComment(@"An external method.", null, null, null, null, false, null, [new XmlParameterComment(@"name", @"The name of the tester. Defaults to ""Tester"".", null, false)], null));
+            _cache.Add(new MemberKey(typeof(global::ClassLibrary.Endpoints), MemberType.Method, "CreateHolder", typeof(global::ClassLibrary.Holder<>), [typeof(object)]), new XmlComment(@"Creates a holder for the specified value.", null, null, @"A holder for the specified value.", null, false, [@"{ value: 42 }"], [new XmlParameterComment(@"value", @"The value to hold.", null, false)], null));
 
 
             return _cache;

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs

@@ -8,6 +8,9 @@
 // </auto-generated>
 //------------------------------------------------------------------------------
 #nullable enable
+// Suppress warnings about obsolete types and members
+// in generated code
+#pragma warning disable CS0612, CS0618
 
 namespace System.Runtime.CompilerServices
 {
@@ -268,7 +271,7 @@ Note that there isn't a way to provide a ""cref"" to
 {
     Console.WriteLine(c);
 }```"], [new XmlParameterComment(@"left", @"The left operand of the addition.", null, false), new XmlParameterComment(@"right", @"The right operand of the addition.", null, false)], null));
-            _cache.Add(new MemberKey(typeof(global::ExampleClass), MemberType.Method, "AddAsync", typeof(global::System.Threading.Tasks.Task<global::System.Int32>), [typeof(global::System.Int32), typeof(global::System.Int32)]), new XmlComment(@"This method is an example of a method that
+            _cache.Add(new MemberKey(typeof(global::ExampleClass), MemberType.Method, "AddAsync", typeof(global::System.Threading.Tasks.Task<>), [typeof(global::System.Int32), typeof(global::System.Int32)]), new XmlComment(@"This method is an example of a method that
 returns an awaitable item.", null, null, null, null, false, null, null, null));
             _cache.Add(new MemberKey(typeof(global::ExampleClass), MemberType.Method, "DoNothingAsync", typeof(global::System.Threading.Tasks.Task), []), new XmlComment(@"This method is an example of a method that
 returns a Task which should map to a void return type.", null, null, null, null, false, null, null, null));

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/OperationTests.SupportsXmlCommentsOnOperationsFromControllers#OpenApiXmlCommentSupport.generated.verified.cs

@@ -8,6 +8,9 @@
 // </auto-generated>
 //------------------------------------------------------------------------------
 #nullable enable
+// Suppress warnings about obsolete types and members
+// in generated code
+#pragma warning disable CS0612, CS0618
 
 namespace System.Runtime.CompilerServices
 {