dotnet / dotnet/aspnetcore

XML doc `<summary>` is dropped for *inherited* properties of a controller's complex query parameter

Open
#67,610 2 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

When a controller action takes a complex `[FromQuery]` parameter and that type **inherits** properties from a base class, the XML `` of the **inherited** properties is not emitted as the OpenAPI parameter `description`. The `` of properties declared **directly** on the action-parameter type is emitted correctly.

For example, in the following case:
```cs
public class BaseParam
{
/// Filter by id.
public string? Id { get; set; }
}

public class Param : BaseParam
{
/// Filter by name.
public string? Name { get; set; }
}

IActionResult Get([FromQuery] Param p)
```

Only the directly-declared `Name` gets a `description`; the inherited `Id` has none.

```json
"parameters": [
{
"name": "Name",
"in": "query",
"description": "Filter by name.",
"schema": { "type": "string" }
},
{
"name": "Id",
"in": "query",
"schema": { "type": "string" }
}
]
```

### Expected Behavior

In the example above both `Name` (declared) and `Id` (inherited) should get their `` as the parameter `description`.

### Steps To Reproduce

`.csproj`:

```xml


net10.0
enable
enable
true



```

`Program.cs`:

```csharp
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();
app.MapControllers();
app.Run();

public class BaseParam
{
/// Filter by id.
public string? Id { get; set; }
}

public class Param : BaseParam
{
/// Filter by name.
public string? Name { get; set; }
}

[ApiController]
[Route("Items")]
public class ItemsController : ControllerBase
{
[HttpGet]
public IActionResult Get([FromQuery] Param p) => Ok();
}

```

Run and GET `/openapi/v1.json`, look at `paths./items.get.parameters`.

### Exceptions (if any)

_No response_

### .NET Version

10.0.301

### Anything else?

`Microsoft.AspNetCore.OpenApi` 10.0.9

Contributor guide

Open the contributing guide

Research direction

Start with the Program.cs reproduction and the Microsoft.AspNetCore.OpenApi setup in the .csproj, then trace the MapOpenApi generation path for complex [FromQuery] parameters. Add or update coverage for inherited and directly declared properties, and verify that both XML summaries appear as parameter descriptions in /openapi/v1.json.

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
73/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.