如何在ASP.Net Core中使用Swagger

您通常会想为您的API创建文档。 要创建此文档，您可以利用Swagger （可用于轻松提供API的UI表示）的工具。 为API生成Swagger文档后，您可以查看API方法的签名，甚至可以测试API方法。

Swashbuckle是一个用于生成Swagger文档的开源项目。 本文讨论了如何利用Swashbuckle为RESTful API生成交互式文档。

[Microsoft .Net 5将.Net Framework和.Net Core结合在一起：了解.Net Standard和.Net Core的合并对开发人员意味着什么 。 | 从InfoWorld的Microsoft Architect博客中了解如何从.Net Framework和.Net Core中获得最大收益。 | 通过InfoWorld的App Dev Report新闻通讯了解编程方面的热门话题。 ]

创建一个ASP.Net Core项目

首先，让我们在Visual Studio中创建一个ASP.Net Core项目。 假设系统中已安装Visual Studio 2017或Visual Studio 2019，请按照以下概述的步骤在Visual Studio中创建新的ASP.Net Core项目。

1. 启动Visual Studio IDE。
2. 点击“创建新项目”。
3. 在“创建新项目”窗口中，从显示的模板列表中选择“ ASP.Net Core Web应用程序”。
4. 点击下一步。
5. 在接下来显示的“配置新项目”窗口中，指定新项目的名称和位置。
6. 单击创建。
7. 在“创建新的ASP.Net Core Web应用程序”窗口中，从顶部的下拉列表中选择.Net Core作为运行时，并选择ASP.Net Core 2.2（或更高版本）。
8. 选择“ API”作为项目模板，以创建一个新的ASP.Net Core Web API项目。
9. 确保未选中“启用Docker支持”和“配置HTTPS”复选框，因为我们此处将不再使用这些功能。
10. 确保将身份验证设置为“无身份验证”，因为我们也不会使用身份验证。
11. 单击创建。

按照这些步骤将在Visual Studio中创建一个新的ASP.Net Core项目。 我们将在本文的后续部分中使用该项目，以研究如何为ValuesController生成Swagger文档。

在ASP.Net Core中安装Swagger中间件

如果您已经成功创建了ASP.Net Core项目，则下一步是将必要的NuGet包添加到项目中。 为此，请在“解决方案资源管理器”窗口中选择项目，右键单击并选择“管理NuGet软件包...”。在NuGet软件包管理器窗口中，搜索软件包Swashbuckle.AspNetCore并安装它。 或者，您可以通过NuGet软件包管理器控制台安装软件包，如下所示。

PM> Install-Package Swashbuckle.AspNetCore

Swashbuckle.AspNetCore软件包包含必要的工具，用于为ASP.Net Core生成API文档。

在ASP.Net Core中配置Swagger中间件

要配置Swagger，请在ConfigureServices方法中编写以下代码。 请注意，如何使用AddSwaggerGen扩展方法来指定API文档的元数据。

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "Swagger Demo",
                    Description = "Swagger Demo for ValuesController",
                    TermsOfService = "None",
                    Contact = new Contact() { Name = "Joydip Kanjilal",
                    Email = "joydipkanjilal@yahoo.com",
                    Url = "www.google.com" }
                });
            });

您还应该在Configure方法中启用Swagger UI，如下所示。

app.UseSwagger();
app.UseSwaggerUI(c =>
{
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
});

这是Startup类的完整代码，供您参考。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;
namespace IDGSwaggerDemo
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }
        public IConfiguration Configuration { get; }
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion
            (CompatibilityVersion.Version_2_2);   
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "Swagger Demo",
                    Description = "Swagger Demo for ValuesController",
                    TermsOfService = "None",
                    Contact = new Contact() { Name = "Joydip Kanjilal",
                    Email = "joydipkanjilal@yahoo.com",
                    Url = "www.google.com"
                }
                });
            });
        }
        public void Configure(IApplicationBuilder app,
       IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            app.UseMvc();
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
            });
        }
    }
}

这就是开始使用Swagger所需要做的全部工作。

浏览ASP.Net Core应用程序的Swagger UI

现在，我们准备执行应用程序并浏览Swagger端点。 Swagger UI如下图1所示。 请注意Swagger如何为HTTP动词GET，PUT，POST和DELETE使用不同的颜色。 您可以直接从Swagger UI执行图1所示的每个端点。

IDG

图1：动作敏捷。

在控制器的操作方法中创建XML注释

到目前为止，一切都很好。 在之前生成的Swagger文档中，没有XML注释。 如果要在Swagger文档中显示XML注释，则只需在控制器的action方法中编写这些注释即可。

现在让我们为ValuesController中的每个操作方法编写注释。 这是ValuesController的更新版本，其中包含每个操作方法的XML注释。

  [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        /// <summary>
        /// Get action method without any argument
        /// </summary>
        /// <returns></returns>
        [HttpGet]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }
        /// <summary>
        /// Get action method that accepts an integer as an argument
        /// </summary>
        /// <param name="id"></param>
        /// <returns></returns>
        [HttpGet("{id}")]
        public ActionResult<string> Get(int id)
        {
            return "value";
        }
        /// <summary>
        /// Post action method to add data
        /// </summary>
        /// <param name="value"></param>
        [HttpPost]
        public void Post([FromBody] string value)
        {
        }
        /// <summary>
        /// Put action method to modify data
        /// </summary>
        /// <param name="id"></param>
        /// <param name="value"></param>
        [HttpPut("{id}")]
        public void Put(int id, [FromBody] string value)
        {
        }
        /// <summary>
        /// Delete action method
        /// </summary>
        /// <param name="id"></param>
        [HttpDelete("{id}")]
        public void Delete(int id)
        {
        }
    }

在Swagger中打开XML注释

请注意，默认情况下Swagger不显示XML注释。 您需要打开此功能。 为此，请在Project上单击鼠标右键，选择Properties，然后导航到Build选项卡。 在“构建”选项卡中，选中“ XML文档文件”选项以指定XML文档文件的创建位置。

您还应该通过在ConfigureServices方法中编写以下代码来指定在生成Swagger文档时应包含XML注释。

c.IncludeXmlComments(@"D:\Projects\IDG\IDGSwaggerDemo\IDGSwaggerDemo\IDGSwaggerDemo.xml");

这就是在Swagger中打开XML注释所需要做的一切。

将应用程序的启动URL设置为Swagger UI

您可以更改应用程序启动URL，以指定在启动应用程序时将加载Swagger UI。 为此，请在Project上单击鼠标右键，然后选择Properties。 然后导航到“调试”选项卡。 最后，将Launch Browser值指定为swagger，如图2所示。

IDG

图2：将启动URL设置为Swagger。

当再次运行该应用程序并导航到Swagger URL时，您将看到Swagger UI，如下图3所示。 这次请注意每个API方法中的XML注释。

IDG

图3：Swagger UI显示控制器的操作方法的XML注释。

Swashbuckle是为您的API生成Swagger文档的好工具。 最重要的是，Swashbuckle易于配置和使用。 Swagger所能提供的功能比我们在这里看到的要多得多。 您可以使用级联样式表来自定义Swagger UI，将枚举值显示为字符串值，并为API的不同版本创建不同的Swagger文档，仅举几例。

From: https://www.infoworld.com/article/3400084/how-to-use-swagger-in-aspnet-core.html