Issues with OpenAPI generation and XML comments compatibility in .NET 10 preview 4 controller APIs

[itbencn]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I have been testing the OpenAPI document generation in the .NET 10 Preview 4 version of the aspnetcore project for controller-based APIs (mini APIs are not tested or discussed here).

Expected Behavior

I encountered several issues related to how XML comments interact with OpenAPI generation:

1. XML <response> comments on controller action methods:
   The official documentation mentions support for XML <response> tags, but these do not seem to be translated into OpenAPI paths.responses. That is, the responses described in XML are missing from the generated OpenAPI YAML/JSON under the paths section.

2. XML comments on controller classes:

   • The class-level <summary> element is not converted into OpenAPI tags.name.
   • The class-level <remarks> element is not converted into OpenAPI tags.description.

   For comparison, applying [Tags("tagName")] attribute on the controller works fine and the tag name shows up correctly.
   Applying [Description("desc")] attribute on the controller does not translate into the tag's description, either.

3. Enum support in OpenAPI schema:

   • The current OpenAPI document generation does not correctly support enums.
   • Enum options are missing from the generated OpenAPI schema, even though they are present in the XML documentation.
   • According to OpenAPI specification, enums can be declared with enum: ["name1", "name2"] or enum: [1, 2].
   • It appears this feature is not properly supported or implemented yet in the .NET 10 preview 4 version.

Finally, a question for discussion:

• What is the recommended practice or approach to include enum member (individual enum value) documentation/comments into the OpenAPI documentation? For example, how to make each enum member's XML <summary> or other annotations appear in the OpenAPI schema description or extensions?

Would appreciate any guidance or roadmap clarification on these points.

Thanks!

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

10.0.100-preview.4.25258.110

Anything else?

No response

[itbencn]

Making OpenAPI compatible with XML comments is a highly meaningful improvement direction. This has been a shortcoming in .NET 9, so I’m glad to see such plans in the .NET 10 preview.

In .NET 9 Web API, to enrich and improve OpenAPI documentation, a heavy reliance on various Attributes is required, which brings two serious problems:


1. It causes extensive changes to existing project code, resulting in significant code intrusion and higher maintenance costs.
2. XML comments are an irreplaceable documentation method in both existing and new projects. They clearly describe classes, methods, and parameters and provide IDE tooling support such as IntelliSense, enhancing development efficiency and team collaboration standards.
   However, to achieve comprehensive OpenAPI documentation, the same comment content must be redundantly declared again via Attributes, which leads to cluttered code structure and repeated content, reducing readability.
   
   Therefore, it is hoped that .NET 10 can better utilize existing XML comments, and achieve a cleaner, simpler, and more consistent OpenAPI documentation generation experience.

[martincostello]

Have you tried out the .NET 10 previews to see if the changes already implemented address your feedback?

[itbencn]

Have you tried out the .NET 10 previews to see if the changes already implemented address your feedback?

The above issue is based on version 10.0.100-preview.4.25258.110

[captainsafia]

@itbencn Are you able to share a repro of the issues that you are seeing?

XML comments on controller classes:

The class-level

element is not converted into OpenAPI tags.name.
The class-level element is not converted into OpenAPI tags.description.

We don't support this kind of mapping at the moment. The fact that the controller name ends up being the tag is an implementation detail of the current document generation. We can consider going further with this assumption and making it so that <summary> on controller classes maps to tags.description. I don't think it makes sense to map <summary> to tags.name given the way people use <summary>.

Enum support in OpenAPI schema:

You may need some custom JSON options here depending on how you are using enums. Do you have a simple repro?

[itbencn]

@captainsafia
The class-level
Thank you for your feedback. I have re-reviewed the OpenAPI documentation, and indeed, mapping the XML <summary> to the OpenAPI tags.description is a more reasonable approach.

Enum support in OpenAPI schema
In the .NET 10 Preview version, the generated OpenAPI document completely lacks the enum property field for enum types. However, according to the OpenAPI specification, this field should be present. Other tools like swagger and scalar API documentation tools handle this correctly.

Here is a sample code snippet:

/// <summary>
/// enum-summary-ExampleEnum
/// </summary>
/// <remarks>enum-remarks</remarks>
public enum ExampleEnum
{
    /// <summary>
    /// enum-value-summary-FirstValue
    /// </summary>
    FirstValue = 1,
    /// <summary>
    /// enum-value-summary-SecondValue
    /// </summary>
    SecondValue = 5,
    /// <summary>
    /// enum-value-summary-ThirdValue
    /// </summary>
    ThirdValue = 9
}

Ideally, the generated portion of the OpenAPI document should look like this:

{
     // other
     "components": {
          "schemas": {
               "ExampleEnum": {
                    "type": "integer",
                    "description": "enum-summary-ExampleEnum",
                    "enum": [1, 5, 9]
                    //"x-enum-description": ["enum-value-summary-FirstValue", "enum-value-summary-SecondValue", "enum-value-summary-ThirdValue"]
               }
          }
     }
}

The enum field should conform to the OpenAPI specification, but it is currently missing in the .NET 10 Preview 4 version. I recommend prioritizing this issue.
As for the x-enum-description, this is just an example I provided, and it does not conform to the OpenAPI specification, so it is only for discussion purposes and has a relatively lower priority. For more information, please refer to the OAI/OpenAPI-Specification#348.

Looking forward to your further guidance. Thank you!