dotnet / dotnet/aspnetcore

OpenAPI: Provide an attribute for ignoring parameters/properties

Open
#65,929 4 comments 2 reactions 0 assignees View on GitHub
api-proposal api-suggestion area-minimal feature-openapi Needs: Attention :wave:
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 6h
Merged PRs (30d)
290

Description

## Background and Motivation

When parameters or properties are set by middleware or otherwise managed internally, there should be a way to hide them from the generated OpenAPI spec.

The existing `ApiExplorerSettingsAttribute` can only be used on classes/methods, not individual parameters/properties.

## Proposed API

Provide an attribute similar to Swashbuckle's `[SwaggerIgnore]` that can be used on parameters and properties to exclude them from the generated OpenAPI spec.

```csharp
namespace Microsoft.AspNetCore.OpenApi;

[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property)]
public sealed class OpenApiIgnoreAttribute : Attribute
{
}
```

## Usage Examples

```csharp
public sealed class CreateOrderRequest
{
public required string Name { get; init; }

[OpenApiIgnore]
public string? TenantId { get; set; }
}
```

```csharp
app.MapGet("/orders", ([OpenApiIgnore] TenantContext tenantContext) =>
{
// tenantContext is populated my middleware and should not appear in OpenAPI.
});
```

## Alternative Designs

Consumers can use OpenAPI transformers to remove these parameters/properties manually, but that requires each project to implement the same behavior.

Another option would be to extend an existing attribute, such as `ApiExplorerSettingsAttribute` or `ExcludeFromDescriptionAttribute`, to support parameters/properties.

## Risks

This could cause the generated OpenAPI spec to omit parameters or properties that clients actually need if the attribute is used incorrectly.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.