ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】

⒈新建ASP.NET Core WebAPi项目

⒉添加 NuGet 包

Install-Package Swashbuckle.AspNetCore

⒊Startup中配置

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using Swashbuckle.AspNetCore.Swagger;

 namespace SwaggerXmlDemo
 {
     public class Startup
     {
         public Startup(IConfiguration configuration)
         {
             Configuration = configuration;
         }

         public IConfiguration Configuration { get; }

         // This method gets called by the runtime. Use this method to add services to the container.
         public void ConfigureServices(IServiceCollection services)
         {
             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

             //注册Swagger生成器，定义一个和多个Swagger 文档
             services.AddSwaggerGen(option =>
             {
                 //配置第一个Doc
                 option.SwaggerDoc("v1", new Info
                 {
                     Version = "v1",
                     Title = "My API_1",
                     Description = "Document Api",
                     Contact = new Contact
                     {
                         Name = "fanqi",
                         Email = "[e-mail]",
                         Url = "https://www.coreqi.cn"
                     }
                 });
             });
         }

         // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
         public void Configure(IApplicationBuilder app, IHostingEnvironment env)
         {
             if (env.IsDevelopment())
             {
                 app.UseDeveloperExceptionPage();
             }

             //启用中间件服务生成Swagger作为JSON终结点
             app.UseSwagger();

             //启用中间件服务对swagger-ui，指定Swagger JSON终结点
             app.UseSwaggerUI(c =>
             {
                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "DemoAPI V1");
                 //c.RoutePrefix = "swagger";  //默认
                 c.RoutePrefix = string.Empty;
             });

             app.UseMvc();
         }
     }
 }

⒋添加注释信息

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;

 namespace SwaggerXmlDemo.Models
 {
     /// <summary>
     /// 用户实体类
     /// </summary>
     public class User
     {
         /// <summary>
         /// 用户主键Id
         /// </summary>
         /// <example></example>
         public int id { get; set; }
         /// <summary>
         /// 用户名
         /// </summary>
         /// <example>fanqi</example>
         public string username { get; set; }
         /// <summary>
         /// 用户密码
         /// </summary>
         /// <example>admin</example>
         public string password { get; set; }
         /// <summary>
         /// 用户年龄
         /// </summary>
         /// <example></example>
         public int? age { get; set; }
         /// <summary>
         /// 用户邮箱
         /// </summary>
         /// <example>[e-mail]</example>
         public string email { get; set; }
     }
 }

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
 using Microsoft.AspNetCore.Http;
 using Microsoft.AspNetCore.Mvc;
 using SwaggerXmlDemo.Models;

 namespace SwaggerDemo.Controllers
 {
     /// <summary>
     /// 用户Api控制器
     /// </summary>
     [Route("api/[controller]")]
     [ApiController]
     public class UserController : ControllerBase
     {
         /// <summary>
         /// 获取系统用户列表
         /// </summary>
         /// <remarks>
         /// Demo
         /// Get /api/user/get
         /// </remarks>
         /// <returns>系统用户列表</returns>
         /// <response code="201">返回用户列表</response>
         /// <response code="401">没有权限</response>
         [HttpGet("get")]
         [ProducesResponseType()]
         [ProducesResponseType()]
         public IList<User> GetUsers()
         {
             return new List<User>
             {
                 new User{ id = ,username = "fanqi",password = "admin",age = ,email = "[e-mail]"},
                 new User{ id = ,username = "gaoxing",password = "admin",age = ,email = "[e-mail]"}
             };
         }

         /// <summary>
         /// 新建用户
         /// </summary>
         /// <param name="user">新建用户信息</param>
         /// <returns>是否创建成功信息</returns>
         [HttpPost("add")]
         public IActionResult CreateUser([FromForm] User user)
         {
             return Ok();
         }
     }
 }

⒋启用XML注释

　　1.右键单击“解决方案资源管理器”中的项目，然后选择“属性”

　　2.勾选“生成”选项卡“输出”部分的“XML 文档文件”框

右键生成的XML文件，选择属性。修改“复制到输出目录”为“始终复制”。

启用 XML 注释后会为未记录的公共类型和成员提供调试信息将会出现很多CS1591警告信息。直接无视即可。

警告   CS1591	缺少对公共可见类型或成员“xxxxx”的 XML 注释 指定了 /doc 编译器选项，但是一个或多个构造没有注释。

如果有强迫症，可以按照下图所示进行取消

注意上面生成的xml文档文件的路径，

注意：

​ 1.对于 Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如，“SwaggerDemo.xml”文件在 Windows 上有效，但在 CentOS 上无效。

​ 2.获取应用程序路径，建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

⒌为 Swagger JSON和UI设置xml文档注释路径

         // This method gets called by the runtime. Use this method to add services to the container.
         public void ConfigureServices(IServiceCollection services)
         {
             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

             //注册Swagger生成器，定义一个和多个Swagger 文档
             services.AddSwaggerGen(option =>
             {
                 //配置第一个Doc
                 option.SwaggerDoc("v1", new Info
                 {
                     Version = "v1",
                     Title = "My API_1",
                     Description = "Document Api",
                     Contact = new Contact
                     {
                         Name = "fanqi",
                         Email = "[e-mail]",
                         Url = "https://www.coreqi.cn"
                     }
                 });

                 // 为 Swagger JSON and UI设置xml文档注释路径
                 //var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                 //var xmlPath = Path.Combine(basePath, "SwaggerXmlDemo.xml");
                 var filePath = Path.Combine(System.AppContext.BaseDirectory, "SwaggerXmlDemo.xml");
                 option.IncludeXmlComments(filePath);
             });
         }

⒍查看效果