.Net Core WebApi(2)—Swagger

上一个版本的入门Swagger提示不够完整，这章着重完善和优化

Swagger用于将我们编写的接口自动生成规范化的文档，便于进行测试和对接 

 

一.创建Swagger

1.1  Nuget 安装  Swashbuckle.AspNetCore

如图：

 

 

1.2  添加服务

在Startup.cs中，编辑Configure和ConfigureServices

 

// 使用此方法向容器添加服务
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc();
 
 
            #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = " MyAPi", 
                });
            });
            #endregion
        }
 
 
        // 使用此方法配置HTTP请求管道
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
 
 
            app.UseMvc();
 
 
            #region Swagger
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
            });
            #endregion
        }

 

 此时运行， 在域名后加/Swagger,确认即可看到Swagger的UI界面

 

二.优化Swagger

 

2.1 设置为启动项

修改launchSettings.json中的“launchUrl”,系统即可运行后直接显示SwaggerUI界面

 

 

2.2 接口参数提示

（1）右击项目文件=》属性=》生成=》输出=》勾选“生成xml文档”。

编译成功后，就会在对应的文件夹下生成自己命名的XML文件

 

（2）读取上一步生成的XML

  启动类Startup.cs中添加Swagger服务读取这个XML文件

  Nuget 安装  Microsoft.Extensions.PlatformAbstractions;

 

public void ConfigureServices(IServiceCollection services)
{
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            #region Swagger
            services.AddSwaggerGen(s =>
            {
                s.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "  WebAPI" 
                });
                //添加读取注释服务
                var basePath = 
               PlatformServices.Default.Application.ApplicationBasePath;
                //项目属性 XML的配置名称  APIHelp.xml
                var xmlPath = Path.Combine(basePath, "APIHelper.xml");
                s.IncludeXmlComments(xmlPath);
            });
            #endregion
}

 

运行后，如下图所示：

 

 2.3 控制器名称提示

创建文件夹“ SwaggerHelp”，添加“ SwaggerDocTag.cs”，完整代码如下

using Microsoft.Extensions.PlatformAbstractions;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using System.Xml;
namespace CWIOS.WebApi.SwaggerHelp
{
    /// <summary>
    /// Swagger注释帮助类
    /// </summary>
    public class SwaggerDocTag : IDocumentFilter
    {
        /// <summary>
        /// 添加附加注释 初始化
        /// </summary>
        /// <param name="swaggerDoc"></param>
        /// <param name="context"></param>
        public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
        {
            swaggerDoc.Tags = GetControllerDesc();
        }
        /// <summary>
        /// 从xml注释中读取控制器注释
        /// </summary>
        /// <returns></returns>
        private List<Tag> GetControllerDesc()
        {
            List<Tag> tagList = new List<Tag>();
            var basePath = PlatformServices.Default.Application.ApplicationBasePath;
            var xmlpath = Path.Combine(basePath, "APIHelper.xml");
            if (!File.Exists(xmlpath))//检查xml注释文件是否存在
                return tagList;
            XmlDocument xmlDoc = new XmlDocument();
            xmlDoc.Load(xmlpath);
            string memberName = string.Empty;//xml三级节点的name属性值
            string controllerName = string.Empty;//控制器完整名称
            string key = string.Empty;//控制器去Controller名称
            string value = string.Empty;//控制器注释
            foreach (XmlNode node in xmlDoc.SelectNodes("//member"))//循环三级节点member
            {
                memberName = node.Attributes["name"].Value;
                if (memberName.StartsWith("T:"))//T:开头的代表类
                {
                    string[] arrPath = memberName.Split('.');
                    controllerName = arrPath[arrPath.Length - 1];
                    if (controllerName.EndsWith("Controller"))//Controller结尾的代表控制器
                    {
                        XmlNode summaryNode = node.SelectSingleNode("summary");//注释节点
                        key = controllerName.Remove(controllerName.Length -  "Controller".Length, "Controller".Length);
                        if (summaryNode != null &&  !string.IsNullOrEmpty(summaryNode.InnerText) && !tagList.Contains(new Tag { Name = key }))
                        {
                            value = summaryNode.InnerText.Trim();
                            tagList.Add(new Tag { Name = key, Description = value });
                        }
                    }
                }
            }
            return tagList;
        }
    }
}

 

修改启动类“Startup.cs”中的“ConfigureServices”

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            #region Swagger
            services.AddSwaggerGen(s =>
            {
                s.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = " WebAPI",
                   
                });
                //添加读取注释服务
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                //项目属性 XML的配置名称  APIHelp.xml
                var xmlPath = Path.Combine(basePath, "APIHelper.XML"); 
                s.IncludeXmlComments(xmlPath);
 
                //添加对控制器的标签(描述)
                s.DocumentFilter<SwaggerDocTag>();
            });
            #endregion
        }
 

 

结果如下图：

 

2.4 实体类注释

新建类库“项目名称.Entity”，并添加“Student类”

  

public class Student
    {
        /// <summary>
        /// 姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 年龄
        /// </summary>
        public int Age { get; set; }
    }

 

(1) 生成实体类的XML文件，步骤类似2.2，不同的是生成路径需要修改，如下图：

 

在WebAPi项目中引用实体类库的dll,重新生成，在对应文件夹下能看到对应的两个XML

 

(2)读取实体类库的XML

修改启动类“Startup.cs”中的“ConfigureServices”,如下图所示：

   

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            #region Swagger
            services.AddSwaggerGen(s =>
            {
                s.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = " WebAPI", 
                   
                });
                //添加读取注释服务
                var basePath = PlatformServices.Default.Application.ApplicationBasePath;
                //项目属性 XML的配置名称  APIHelp.xml
                var xmlPath = Path.Combine(basePath, "APIHelper.XML");
                var entityXmlPath = Path.Combine(basePath, "CWIOS.Entity.xml");
                s.IncludeXmlComments(xmlPath,true);
                //添加实体层注释
                s.IncludeXmlComments(entityXmlPath);
                //添加对控制器的标签(描述)
                s.DocumentFilter<SwaggerDocTag>();
            });
            #endregion
        }
 

 

新增AddStudent 接口：

  /// <summary>
        /// 新增学生
        /// </summary>
        /// <param name="student">学生实体类</param>
        [HttpPost("AddStudent")]
        public ActionResult AddStudent(Student student)
        {
            return Ok("成功");
        }
 

 

最终效果如下图所示：

 

参考链接：https://www.cnblogs.com/RayWang/p/9216820.html