Asp.net Core Web API使用Swagger创建帮

Asp.net Core Web API使用Swagger生成帮助页，Swagger使用内置技术创建一个API接口的帮助页面，页面不仅使API接口一目了然，而且把接口注释也显示在帮助页上，最大的特点是支持接口的在线测试。这些优点无疑使其比原先使用的Asp.net 内置的API帮助文档更受欢迎。

引用Swagger NuGet packages

• 使用程序包管理器控制台窗口:
  Install-Package Swashbuckle.AspNetCore
• 使用NuGet管理界面安装
  右键项目>选择管理NuGet选项>在管理解决方案包里面搜索 Swashbuckle.AspNetCore>选择Swashbuckle.AspNetCore并安装。
  Swashbuckle.AspNetCore安装界面

在项目中添加及设置ConfigureServices中间件

在Startup类的ConfigureServices方法添加如下代码，使项目中添加ConfigureServices中间件

  services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });

在Startup类的Configure，使项目能够使用ConfigureServices中间件

  // 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.
   services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",       
                    Title = "ToDo API",
                    Description = "A simple example ASP.NET Core Web API ",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "凌云木", Email = "825116693@qq.com", Url = "https://www.jianshu.com/u/79758fa3d8b0" },
                    License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
                });
            });

运行调试

http://localhost:35030/swagger/ 不同的电脑可能会有不同的端口号

接口帮助文档
调试接口

启用XML 注释

image.png

另外上图中，禁止显示警告中，添加1591 代码，可以过滤掉一些类名没有写注释的报警信息

在Startup类的Configure方法上，修改使用ConfigureServices中间件的调用方法

         services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",       
                    Title = "ToDo API",
                    Description = "A simple example ASP.NET Core Web API ",
                    TermsOfService = "None",
                    Contact = new Contact { Name = "凌云木", Email = "825116693@qq.com", Url = "https://www.jianshu.com/u/79758fa3d8b0" },
                    License = new License { Name = "Use under LICX", Url = "https://example.com/license" }
                });
                //为Swagger的JSON和UI设置XML注释
                var basePath = AppContext.BaseDirectory;
                var xmlPath = Path.Combine(basePath, "TodoApi.xml");
                c.IncludeXmlComments(xmlPath);
            });

在前面的代码中，AppicationBasePath获取应用程序的基本了路径。用来查找XML注释文件.TodoApi.xml仅适用于此示例中，引文生成的XML注释文件的名称基于应用程序的名称。

修改完运行调试

image.png