c# - 如何在 ASP.NET Core 的 Swagger 中包含 XML 注释文件

Question

我需要 Swagger 生成 API 文档，包括用于测试操作的 UI。

在我的项目中使用 ASP.NET 时，生成了 deps XML 文件，一切正常，如下所示:

但是当我在我的项目中使用 ASP.NET Core 时，没有生成 deps XML 文件。它只是生成我的项目评论 XML 文件，如下所示:

当我将项目部署到 IIS 时，项目 XML 不在部署文件列表中。

Answer 1

对于 .Net Core 2 到 3.1 版本，它略有不同，对于那些使用较新版本遇到它的人，您可以创建自己的 private void ConfigureSwagger(IServiceCollection services) 构造函数，添加对 swagger services.AddSwaggerGen(c => { c.SwaggerDoc(/*populate with your info */);然后定义一个新参数，它将成为您的 XML 文档的路径: var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml"); c.IncludeXmlComments(filePath);.

它应该看起来像这样:

private void ConfigureSwagger(IServiceCollection services)
    {
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new Info
            {
                Version = "v1",
                Title = "YourApiName",
                Description = "Your Api Description.",
                TermsOfService = "None",
                Contact = new Contact
                    {Name = "Contact Title", Email = "contactemailaddress@domain.com", Url = ""}
            });
            var filePath = Path.Combine(AppContext.BaseDirectory, "YourApiName.xml");
            c.IncludeXmlComments(filePath);
        });
    }

为此，您需要确保构建的输出已检查文档文件(见红色箭头)并正确设置路径。我注意到您可以去掉预填充的路径，只使用 bin\YourApiName.xml，如下所示:

更新:如果这些更改没有按预期工作，请检查配置。在示例中，配置设置为调试。如果您从不同的环境 (env) 运行，您可能需要检查这些设置是否适用于该环境。

更新 2:自 OpenAPI 发布以来，我想我应该更新我的示例(下方)以显示对 this specification 的更准确引用这应该遵循类似于:

services.AddSwaggerGen(o =>
            {
                o.SwaggerDoc("v1",
                    new OpenApiInfo
                    {
                        Title = "Your API Name",
                        Description = "Your API Description",
                        Version = "v1",
                        TermsOfService = null, 
                        Contact = new OpenApiContact 
                        {
                            // Check for optional parameters
                        },
                        License = new OpenApiLicense 
                        {
                            // Optional Example
                            // Name = "Proprietary",
                            // Url = new Uri("https://someURLToLicenseInfo.com")
                        }
                    });
            });