如何在Swagger文档中包含框架类的摘要?

1wnzp6jl  于 2023-08-05  发布在  其他
关注(0)|答案(1)|浏览(110)

我知道如何使用为我自己的项目生成的XML文档文件,以便Swashbuckle将它们提供给Swagger文档,但是有没有一种方法可以为标准框架类做同样的事情?例如,如果我的API引用了一个系统框架类型,我如何获得Swagger文档中包含的为该类型定义的摘要和文档(并通过IntelliSense可见)?

a2mppw5e

a2mppw5e1#

就像在Swagger文档中包含您自己项目的XML文档一样,您也可以包含.NET Framework或任何其他库的XML文档。
您需要找到库的XML文档文件(它通常与DLL文件位于同一个文件夹中,名称相同,但扩展名为.xml),并将其包含在Swagger配置中。
下面是如何在.NET Core或.NET 5+中执行此操作的方法,首先,确保框架DLL的XML文档文件存在。对于.NET Core或.NET 5+,这些文件通常位于NuGet包存储中(Windows上的%userprofile%.nuget\packages,基于Unix的系统上的~/.nuget/packages)。它们与DLL文件位于同一目录中,具有相同的名称,但扩展名为.xml。
找到XML文件后,可以将其添加到Startup.cs中的Swagger配置中,

public void ConfigureServices(IServiceCollection services)
{

    services.AddSwaggerGen(c =>
    {
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
        
        var frameworkXmlPath = @"<path-to-framework-xml-file>";
        c.IncludeXmlComments(frameworkXmlPath);
    });
}

字符串
请替换为框架DLL的XML文档文件的实际路径。
如果你正在使用Docker或其他容器化/部署技术,请确保XML文件包含在你的部署包中。
PS:并不是.NET框架中的所有类型都有文档记录,即使有,文档也可能不如您为自己的类型编写的那样全面。

相关问题