Fix OpenAPI XML code gen #60977

captainsafia · 2025-03-17T20:10:09Z

Fixes some of the issues in #60783.

captainsafia · 2025-03-17T20:12:29Z

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)


This helps us avoid generating XML comments for non-public types and internal properties in non-public types.

Note: this does mean that DTOs have to be defined as public types if they are defined in the same assembly as the API (see where this is called in the AssemnlyTypeSymbolVisitor above). We can consider changing this behavior to allow XML comments on internal types in the application assembly.

Seems a bit overaggressive. I'm guessing we'll change this behavior a bit in the future.

Any reason to disallow the type entirely just because it has internal types?

I just hit this error in preview 2:

C:\Coding\martincostello\alexa-london-travel-site\artifacts\obj\LondonTravel.Site\debug\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(207,125): error CS0122: 'CustomHttpHeadersMiddleware.Csp' is inaccessible due to its protection level

This relates to a private nested class in public class that has some /// comments on the internal const string members in it.

Would this change fix that scenario too?

One more scenario for you - seems like it's trying to document things to do with the Regex source generator (example):

C:\Coding\martincostello\adventofcode\artifacts\obj\AdventOfCode.Site\debug\Microsoft.AspNetCore.OpenApi.SourceGenerators\Microsoft.AspNetCore.OpenApi.SourceGenerators.XmlCommentGenerator\OpenApiXmlCommentSupport.generated.cs(1589,94): error CS0234: The type or namespace name 'HexColor_1' does not exist in the namespace 'System.Text.RegularExpressions.Generated' (are you missing an assembly reference?)

If not catered for by this change, I can open a new issue.

It depends on whether the type in question is defined in or outside the assembly.

I believe these bits have landed in the nightly preview3 SDK if you want to take another bump to try it out.

Alternatively, I'd recommend filing an issue so we can at least capture this scenario in a test case even if it is already fixed.

I'll try out a nightly tomorrow and see if you think it should be fixed.

Confirmed these two are catered for as of 10.0.100-preview.3.25169.19, but confirmed #61019 is still an issue and found two new ones 😅. Issues shortly...

I think they're probably the same one issue: #61035

I believe these bits have landed in the nightly preview3 SDK if you want to take another bump to try it out.

Alternatively, I'd recommend filing an issue so we can at least capture this scenario in a test case even if it is already fixed.

Found a different case where a private type causes a compiler error.

captainsafia · 2025-03-17T20:13:09Z

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


Suppress obsoletion warnings in generated code. If someone happens to be using an obsolete type in their API, we don't want to resurface this warning in generated code where we call typeof(ObsolteType).

captainsafia · 2025-03-17T20:13:42Z

src/OpenApi/gen/XmlCommentGenerator.Emitter.cs

            {
                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(");


Here and below we format strings in the emitted code so that we can properly escape quoted strings inside XML descriptions/summaries/etc.

captainsafia · 2025-03-17T20:14:33Z

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))})";


We need to make sure that all generics are emitted as open generics for method declarations. We already do this elsewhere in the MemberKey for the declaring type and the property type but not for methods.

captainsafia · 2025-03-17T20:15:32Z

src/OpenApi/sample/Shared/SharedTypes.DeeplyNestedType.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+public class DeeplyNestedLevel1


Since we require all types to be public for discovery, we moved the shared types that are used by tests and the sample app to the sample app since the tests reference the sample app.

Previously, we used compile includes with internal types which doesn't work in this new model.

captainsafia · 2025-03-17T20:20:58Z

.../OpenApiDocumentIntegrationTests.VerifyOpenApiDocument_documentName=controllers.verified.txt

@@ -118,10 +118,12 @@
        "type": "object",
        "properties": {
          "title": {
-            "type": "string"
+            "type": "string",


STJ's schema generation assumes strings are nullable in an oblivious nullability context (see disable in Sample.csproj), hence the delta here.

mikekistler

I didn't really understand all this but everything that I could understand looks fine! 👍

BrennanConroy · 2025-03-18T18:48:35Z

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)


Seems a bit overaggressive. I'm guessing we'll change this behavior a bit in the future.

Any reason to disallow the type entirely just because it has internal types?

captainsafia · 2025-03-18T20:36:18Z

Any reason to disallow the type entirely just because it has internal types?

I assume you mean internal properties? This will omit public properties in internal types.

We can relax the rule a little bit and still discover XML comments on internal types on the application assembly but prohibit them on internal types in referenced files.

This would strike a balance between not discovering internal types in assemblies we don't have access to while still permitting them in the application assembly.

captainsafia requested a review from a team as a code owner March 17, 2025 20:10

ghost added the area-mvc Includes: MVC, Actions and Controllers, Localization, CORS, most templates label Mar 17, 2025

captainsafia commented Mar 17, 2025

View reviewed changes

Fix OpenAPI XML code gen

196bd95

captainsafia force-pushed the cs/openapi-xml-bugfix branch from d231073 to 196bd95 Compare March 17, 2025 20:19

captainsafia commented Mar 17, 2025

View reviewed changes

mikekistler approved these changes Mar 18, 2025

View reviewed changes

BrennanConroy approved these changes Mar 18, 2025

View reviewed changes

Change accessibility checks

c22362a

captainsafia merged commit 06f3c41 into main Mar 19, 2025
27 checks passed

captainsafia deleted the cs/openapi-xml-bugfix branch March 19, 2025 02:42

dotnet-policy-service bot added this to the 10.0-preview3 milestone Mar 19, 2025

This was referenced Mar 20, 2025

[10-preview.2] CS0673 error from XmlCommentGenerator #61019

Open

[OpenAPI] error CS0308: The non-generic type 'TypeName' cannot be used with type arguments #61035

Closed

[OpenAPI] error CS0122: 'Type' is inaccessible due to its protection level #61037

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix OpenAPI XML code gen #60977

Fix OpenAPI XML code gen #60977

captainsafia commented Mar 17, 2025

captainsafia Mar 17, 2025

BrennanConroy Mar 18, 2025

martincostello Mar 19, 2025 •

edited

Loading

martincostello Mar 19, 2025

captainsafia Mar 19, 2025

martincostello Mar 19, 2025

martincostello Mar 20, 2025

martincostello Mar 20, 2025

martincostello Mar 20, 2025

martincostello Mar 20, 2025

captainsafia Mar 17, 2025

captainsafia Mar 17, 2025

captainsafia Mar 17, 2025

captainsafia Mar 17, 2025

captainsafia Mar 17, 2025

mikekistler left a comment

BrennanConroy Mar 18, 2025

captainsafia commented Mar 18, 2025

Fix OpenAPI XML code gen #60977

Fix OpenAPI XML code gen #60977

Conversation

captainsafia commented Mar 17, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martincostello Mar 19, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikekistler left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

captainsafia commented Mar 18, 2025

martincostello Mar 19, 2025 •

edited

Loading