dotnet / dotnet/aspnetcore

Allow adding XML documents at runtime to OpenApi living inside a Nuget Package

Open
#64,439 6 comments 10 reactions 0 assignees View on GitHub
area-minimal feature-openapi investigate
Dominant language
C#
Stars
38.4k
Forks
10.9k
Avg merge
2d 5h
Merged PRs (30d)
276

Description

### Is there an existing issue for this?

- [x] I have searched the existing issues

### Is your feature request related to a problem? Please describe the problem.

Hi Maintainers,

Currently there doesn't seem to be an option to dynamically pass ie. the EntryAssembly XML documents to `AddOpenApi()` if `AddOpenApi()` lives inside a Nuget package which is referenced by the EntryAssembly. This means that we can't generate OpenApi documentation for Controllers/Models that live inside the EntryAssembly.

This is a similar issue to #62941 except **assume** the class library given in that sample repo is a Nuget package referenced by the EntryAssembly.

This feature was previously possible when using [Swashbuckle.WebApi](https://github.com/domaindrivendev/Swashbuckle.WebApi?tab=readme-ov-file#including-xml-comments).

**Example Scenario:**
1. Create Organisation.Common Nuget package with `WebApplication.CreateBuilder()` and all the common bootstrapping code along with `AddOpenApi()` and `MapOpenApi()` in it.
2. EntryAssembly which as Program.Main() references the Organisation.Common Nuget Package
3. EntryAssembly calls the common bootstrapper code.
4. Enable XML documentation for EntryAssembly.
5. Build and run EntryAssembly.
6. No OpenAPI documentation is produced for the Controllers and Models in EntryAssembly.

Thanks

### Describe the solution you'd like

Provide a way to dynamically pass XML documenation files to `AddOpenApi()` just like SwashBuckle so that if an Organisation has a Nuget package with all the common bootstrap code in it then OpenApi documentation can still be generated for the Controllers and Models in the EntryAssembly.

### Additional context

[Enable XML documentation in an ASP.NET Core API project](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/openapi-comments?view=aspnetcore-10.0#enable-xml-documentation-in-an-aspnet-core-api-project)

[Swashbuckle.WebApi](https://github.com/domaindrivendev/Swashbuckle.WebApi?tab=readme-ov-file#including-xml-comments).

#62941

[Microsoft.AspNetCore.OpenApi 10.0.0](https://www.nuget.org/packages/Microsoft.AspNetCore.OpenApi)

```
dotnet --version
10.0.100
```

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.