Swashbuckle

Question

我正在使用 Swagger 来记录我的 .NET C# API，当我的模型在另一个项目上时，Swagger 就崩溃了，没有加载任何东西。

当我从 Visual Studio 加载示例 WebAPI 项目时，它使用同一项目中的模型并且它有效：

但是当我使用其他项目的模型时，它在加载任何东西之前就崩溃了。

我有一个 API 项目和一个商业项目。我的模型是在我的 Buisiness 项目中存储的视图模型（并在其他项目之间共享，因此在那里需要）。

有什么方法可以向 Swagger 指示我的模型定义在哪里？

Answer 1

其实我也想做同样的事情！

我在 Swagger 配置中尝试了这个，其中函数指向我的 XML 文档文件。

c.IncludeXmlComments(GetXmlCommentsPathForControllers());
c.IncludeXmlComments(GetXmlCommentsPathForModels());

它对控制器来说工作正常，但当我记录模型时没有发生太多事情。

Answer 2

我最近在处理托管在 IIS 上的 Web API 项目时遇到了类似的情况。我需要为来自两个不同项目的所有视图模型和模型启用 xml 文档。

下面是工作主要步骤的总结：

为相关项目启用XML文档（参考here）
对于每个项目，先构建它，然后在项目中包含 xml 文件。将文件 "Copy to Output Directory" 的属性设置为 "Copy is newer" 以确保将其复制到服务器的 bin 文件夹中。
在 Swagger 配置中，调用 IncludeXmlComments() 以包含 Simon88 建议的 XML 文档文件。

关键是要确保所有 xml 文档文件都复制到主机服务器的 bin 文件夹中，并且 Swagger UI 知道它们在哪里 :-)。

顺便说一句，类似的问题很少questions/answers。一个是 here

希望对您有所帮助。

Answer 3

来源
1. 型号
2. 网络应用程序

如果 Web 应用程序和模型的源位于不同的项目中，您始终可以生成元数据 xml 并将它们作为构建的一部分复制到 Web 应用程序内的公共位置。

所以在这种情况下，编辑模型的项目属性以将 xml 输出到“..\WebApp\bin”

为了生成动态示例，我建议您完成此 link。

Answer 4

我在使用 Swashbuckle 5.6.0 时遇到了同样的问题，并设法修复如下。通过如下更改项目属性，在包含项目的模型对象上启用 XML 文档文件。

然后进入api项目的SwaggerConfig.cs文件，添加模型对象项目的xml注释文件如下。

c.IncludeXmlComments(string.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory));
// New code line                            
c.IncludeXmlComments(string.Format(@"{0}\bin\core.XML", System.AppDomain.CurrentDomain.BaseDirectory));

现在您将在 swagger 文档上获得 xml 条关于模型属性的评论。

Answer 5

第 1 步：更新参考项目 .csproj 文件并添加 DocumentationFile

    <PropertyGroup>
        <TargetFramework>net6.0</TargetFramework>
        <ImplicitUsings>enable</ImplicitUsings>
        <Nullable>enable</Nullable>
        <GenerateDocumentationFile>True</GenerateDocumentationFile>
        <DocumentationFile>bin$(Configuration)$(TargetFramework)$(MSBuildThisFileName).xml</DocumentationFile>
    </PropertyGroup>

这将导致项目的构建输出 XML 文件以及 bin 文件夹中已编译项目的程序集。

API/Web 项目可以通过对当前正在执行的程序集调用 Assembly.GetReferencedAssemblies() 方法来访问所有具有反射的引用程序集。

第 2 步：更新 swagger 配置

builder.Services.AddSwaggerGen(options =>
{
    options.CustomSchemaIds(type => type.ToString());

    var currentAssembly = Assembly.GetExecutingAssembly();
    var xmlDocs = currentAssembly.GetReferencedAssemblies()
        .Union(new AssemblyName[] { currentAssembly.GetName() })
        .Select(a => Path.Combine(Path.GetDirectoryName(currentAssembly.Location), $"{a.Name}.xml"))
        .Where(f => File.Exists(f)).ToArray();

    Array.ForEach(xmlDocs, (d) =>
    {
        options.IncludeXmlComments(d);
    });

});

Swashbuckle - 从另一个项目的模型向 Swagger UI 添加模型和示例值

Swashbuckle - Add Model and Example values to Swagger UI from a Model from another project

c#

.net

visual-studio-2015

swagger