[OpenAPI] Nullable struct doesn't get description in schema
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 290
Description
### Is there an existing issue for this?
- [x] I have searched the existing issues
### Describe the bug
In a project I use some nullable structs in my API with XML Documentation to give it a description, but this description is not shown in the openapi specification:
```
"components": {
"schemas": {
"MyClass": {
"type": "object",
"description": "My class for demonstration purposes."
},
"MyStruct": {
"type": "object"
},
"MyStruct2": {
"type": "object",
"description": "My second struct for demonstration purposes."
}
}
},
```
### Expected Behavior
I expect that the `XmlCommentSchemaTransformer` ignores the `Nullable<>` type when trying to find the description:
```
"components": {
"schemas": {
"MyClass": {
"type": "object",
"description": "My class for demonstration purposes."
},
"MyStruct": {
"type": "object",
"description": "My struct for demonstration purposes."
},
"MyStruct2": {
"type": "object",
"description": "My second struct for demonstration purposes."
}
}
},
```
### Steps To Reproduce
The following Program.cs in a simple webapi project will reproduce this problem:
```
using Microsoft.AspNetCore.Http.HttpResults;
var builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();
app.MapGet("/nullable-struct", Ok () => TypedResults.Ok(null))
.WithName("GetMyStruct");
app.MapGet("/not-nullable-struct", Ok () => TypedResults.Ok(default))
.WithName("GetMyStruct2");
app.MapGet("/class", Ok () => TypedResults.Ok(null))
.WithName("GetMyClass");
app.Run();
///
/// My struct for demonstration purposes.
///
internal struct MyStruct() { }
///
/// My second struct for demonstration purposes.
///
internal struct MyStruct2() { }
///
/// My class for demonstration purposes.
///
internal class MyClass() { }
```
### Exceptions (if any)
_No response_
### .NET Version
10.0.400
### Anything else?
After some debugging I found that in the 'XmlCommentGenerator.Emitter.cs' the generated code for DocumentationCommentIdHelper doesn't request the underlying type from a nullable type, therefore it will never generate the correct Id.
Contributor guide
Research direction
Start with XmlCommentGenerator.Emitter.cs and inspect the generated DocumentationCommentIdHelper handling for nullable types. Use the provided Program.cs reproduction to compare nullable and non-nullable struct schemas, and verify that the nullable struct's OpenAPI schema includes its XML summary description.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp, openapi
- Domain
- api
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100