dotnet / dotnet/aspnetcore

[OpenAPI] Nullable struct doesn't get description in schema

Open
#69,101 3 comments 0 reactions 0 assignees View on GitHub
area-minimal feature-openapi
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.