将 swagger 集成到 ASP.NET 核心 api 项目中

问题描述

我有一个 ASP.NET 核心 api 项目，我从 .NET 核心 3.1 开始，然后升级到 5.0。它以前没有集成 swagger，现在我想包含它。

我引入了 Swashbuckle.AspNetCore 软件包 v5.6.3。通读此 page，我修改了我的 Startup.cs 以包含 services.AddSwaggerGen(); 以及 app.UseSwagger(); 和 app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json","DemoAPI"));（标准样板内容）。

Startup.cs 的相关部分（目前的情况）：

            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1",new OpenApiInfo
                {
                    Title = "DemoAPI",Version = "v1"
                });
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory,xmlFile);
                c.IncludeXmlComments(xmlPath);
            });

            if (Environment.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                app.UseSwagger();
                app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json","DemoAPI"));
            }

在启动时我看到：

有人可以帮我看看这里需要做哪些进一步的设置吗？

解决方法

这是一个例子。您需要确保 xml 注释文件生成已打开，并且您设置了 entryAssembly 和 apiVersion 变量，即“v1”或您喜欢的任何变量。

运行后，只需访问 /swagger 即可查看全部内容。

// Register the Swagger generator,defining 1 or more Swagger documents
services.AddSwaggerGen(c =>
{
    try
    {
        c.SwaggerDoc(apiVersion,new Microsoft.OpenApi.Models.OpenApiInfo { Title = entryAssembly.GetName().Name,Version = apiVersion });
        foreach (string xmlCommentsFile in Directory.GetFiles(AppContext.BaseDirectory,"*.xml"))
        {
            try
            {
                c.IncludeXmlComments(xmlCommentsFile,true);
            }
            catch
            {
                // nothing to be done,fails in unit tests
            }
        }
    }
    catch
    {
        // nothing to be done,fails in unit tests
    }
});

// later on in app setup
// enable middleware to serve generated Swagger as a JSON endpoint.
app.UseSwagger();

// enable middleware to serve swagger-ui (HTML,JS,CSS,etc.),// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint($"/swagger/{apiVersion}/swagger.json",$"{entryAssembly.GetName().Name} {apiVersion}");
});

,

好的，我发现发生了什么。就我而言，我在现有项目中有几个带有路由的端点，这些端点没有 [HttpGet] 属性。这导致 swagger 出错。一旦我解决了这个问题，现在一切都在运行。