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 = "fanqisoft@163.com",
                        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>1</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>25</example>
        public int? age { get; set; }
        /// <summary>
        /// 用户邮箱
        /// </summary>
        /// <example>fanqisoft@163.com</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(201)]
        [ProducesResponseType(401)]
        public IList<User> GetUsers()
        {
            return new List<User>
            {
                new User{ id = 1,username = "fanqi",password = "admin",age = 25,email = "fanqisoft@163.com"},
                new User{ id = 2,username = "gaoxing",password = "admin",age = 22,email = "gaoxing@163.com"}
            };
        }

        /// <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 = "fanqisoft@163.com",
                        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);
            });
        }

 

⒍查看效果