OpenAPI: Provide an attribute for ignoring parameters/properties
- 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
Assessment
This issue has not been assessed yet.