dotnet / dotnet/aspnetcore

Add pre-generation OpenAPI hook in AddOpenApi options to initialize document metadata

Open
#65,723 5 comments 2 reactions 1 assignee Claimed by @Youssef1313 View on GitHub
api-needs-work api-proposal area-minimal feature-openapi
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 10h
Merged PRs (30d)
281

Description

## Is there an existing issue for this?

- [X] I have searched the existing issues

## Describe the feature request

Please add a new AddOpenApi options hook that runs before operations/paths are generated, so callers can pre-populate the OpenApiDocument.

Today, AddDocumentTransformer runs after generation, which is too late for some scenarios.

Why this is needed

This would enable setting global tag metadata up front (for example richer Tag Object metadata in OpenAPI 3.2), including fields such as summary/description/parent/kind, then letting
generated operations reference those tags naturally.

Spec reference: https://spec.openapis.org/oas/v3.2.0.html#tag-object

Proposed API shape (example)

```csharp
builder.Services.AddOpenApi(options =>
{
options.AddPreGenerationDocumentHook((document, context, token) =>
{
document.Tags ??= [];
document.Tags.Add(new OpenApiTag
{
Name = "users",
Summary = "User operations",
Description = "Endpoints for user lifecycle."
// parent/kind when supported by the model
});
return Task.CompletedTask;
});
});
```

## Proposed execution order

1. Create base document (Info, Servers)
2. Run pre-generation hook
3. Generate paths/operations/components
4. Run existing document transformers

## Additional context

This would complement (not replace) AddDocumentTransformer, and improve support for advanced OpenAPI metadata composition.

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.