Support XML-based OpenAPI docs for minimal and controller-based APIs with Microsoft.AspNetCore.OpenApi (original) (raw)

This issue tracks adding support for enhancing OpenAPI documents generated via the Microsoft.AspNetCore.OpenApi package with XML comments present in both minimal and controller-based APIs and their shared types.

Development for this is happening in preview over in the AspLabs repo in this directory but issues and discussions will happen here.

Eventually, the goal is to stabilize this source generator implementation then fold it into the Microsoft.AspNetCoreOpenApi. Tangentially, there's a soft goal to split out some of the logic for processing XML doc comments into structured metadata via Roslyn analysis into a separate package.

Update from October 26th, 2024:

I've snapped out preview bits of XML support for both Minimal APIs + controller-based APIs out of the AspLabs repo. For now, this package is being shipping in preview out of the dotnet10 package feeds.

$ dotnet new webapi
$ dotnet new nugetconfig
$ dotnet nuget add source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet10/nuget/v3/index.json -n dotnet10
$ dotnet add package Microsoft.AspNetCore.OpenApi.SourceGenerators --prerelease

Currently, he functionality is on-by-default so once you add the package reference above you'll see annotations light up. No modifications to any code are necessary.

Some limitations, caveats, and notes:

• This package assumes that you are using Microsoft.AspNetCore.OpenApi to generate your OpenAPI documents. Under the hood, it's using the transformer APIs in this package to apply the docs.
• This package currently only applies XML docs in the application assembly. External references aren't supported. Apparently, there's some fussing about with MSBuild (and possibly the compiler) to get XML files associated with external references loaded smoothly.
• There isn't super great support for crefs as mentioned in the comment above but this is something I hope to tackle before we ship the package inside Microsoft.AspnetCore.OpenApi for v10.

I've created a branch in the TrainingApi sample app to showcase the current state of the package. You can find that sample over https://github.com/captainsafia/TrainingApi/tree/safia/xml-support.

Open me for old issue content

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

Swashbuckle currently supports reading the XML doc string associated with an action's method to derive the description, summary, example, etc for an action.

We need to add similar support for minimal endpoints where the documentation might be on a referenced method group or (maybe) on a Map* invocation.

Expected Behavior

///

Should resolve the correct summary info.