.Net Core WebApi(2)—Swagger

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

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

 

一.创建Swagger

1.1  Nuget 安装  Swashbuckle.AspNetCore

如图：

 

 

1.2  添加服务

在Startup.cs中，编辑Configure和ConfigureServices

 

 1 // 使用此方法向容器添加服务
 2         public void ConfigureServices(IServiceCollection services)
 3         {
 4             services.AddMvc();
 5  
 6  
 7             #region Swagger
 8             services.AddSwaggerGen(c =>
 9             {
10                 c.SwaggerDoc("v1", new Info
11                 {
12                     Version = "v1.1.0",
13                     Title = " MyAPi", 
14                 });
15             });
16             #endregion
17         }
18  
19  
20         // 使用此方法配置HTTP请求管道
21         public void Configure(IApplicationBuilder app, IHostingEnvironment env)
22         {
23             if (env.IsDevelopment())
24             {
25                 app.UseDeveloperExceptionPage();
26             }
27  
28  
29             app.UseMvc();
30  
31  
32             #region Swagger
33             app.UseSwagger();
34             app.UseSwaggerUI(c =>
35             {
36                 c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
37             });
38             #endregion
39         }

 

 此时运行， 在域名后加/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;

 

 1 public void ConfigureServices(IServiceCollection services)
 2 {
 3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
 4             #region Swagger
 5             services.AddSwaggerGen(s =>
 6             {
 7                 s.SwaggerDoc("v1", new Info
 8                 {
 9                     Version = "v1.1.0",
10                     Title = "  WebAPI" 
11                 });
12                 //添加读取注释服务
13                 var basePath = 
14                PlatformServices.Default.Application.ApplicationBasePath;
15                 //项目属性 XML的配置名称  APIHelp.xml
16                 var xmlPath = Path.Combine(basePath, "APIHelper.xml");
17                 s.IncludeXmlComments(xmlPath);
18             });
19             #endregion
20 }

 

运行后，如下图所示：

 

 2.3 控制器名称提示

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

 1 using Microsoft.Extensions.PlatformAbstractions;
 2 using Swashbuckle.AspNetCore.Swagger;
 3 using Swashbuckle.AspNetCore.SwaggerGen;
 4 using System;
 5 using System.Collections.Generic;
 6 using System.IO;
 7 using System.Linq;
 8 using System.Threading.Tasks;
 9 using System.Xml;
10 namespace CWIOS.WebApi.SwaggerHelp
11 {
12     /// 

13     /// Swagger注释帮助类
14     /// 
15     public class SwaggerDocTag : IDocumentFilter
16     {
17         /// 

18         /// 添加附加注释 初始化
19         /// 
20         /// 
21         /// 
22         public void Apply(SwaggerDocument swaggerDoc, DocumentFilterContext context)
23         {
24             swaggerDoc.Tags = GetControllerDesc();
25         }
26         /// 

27         /// 从xml注释中读取控制器注释
28         /// 
29         /// 
30         private List GetControllerDesc()
31         {
32             List tagList = new List();
33             var basePath = PlatformServices.Default.Application.ApplicationBasePath;
34             var xmlpath = Path.Combine(basePath, "APIHelper.xml");
35             if (!File.Exists(xmlpath))//检查xml注释文件是否存在
36                 return tagList;
37             XmlDocument xmlDoc = new XmlDocument();
38             xmlDoc.Load(xmlpath);
39             string memberName = string.Empty;//xml三级节点的name属性值
40             string controllerName = string.Empty;//控制器完整名称
41             string key = string.Empty;//控制器去Controller名称
42             string value = string.Empty;//控制器注释
43             foreach (XmlNode node in xmlDoc.SelectNodes("//member"))//循环三级节点member
44             {
45                 memberName = node.Attributes["name"].Value;
46                 if (memberName.StartsWith("T:"))//T:开头的代表类
47                 {
48                     string[] arrPath = memberName.Split('.');
49                     controllerName = arrPath[arrPath.Length - 1];
50                     if (controllerName.EndsWith("Controller"))//Controller结尾的代表控制器
51                     {
52                         XmlNode summaryNode = node.SelectSingleNode("summary");//注释节点
53                         key = controllerName.Remove(controllerName.Length -  "Controller".Length, "Controller".Length);
54                         if (summaryNode != null &&  !string.IsNullOrEmpty(summaryNode.InnerText) && !tagList.Contains(new Tag { Name = key }))
55                         {
56                             value = summaryNode.InnerText.Trim();
57                             tagList.Add(new Tag { Name = key, Description = value });
58                         }
59                     }
60                 }
61             }
62             return tagList;
63         }
64     }
65 }

 

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

 1  public void ConfigureServices(IServiceCollection services)
 2         {
 3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
 4             #region Swagger
 5             services.AddSwaggerGen(s =>
 6             {
 7                 s.SwaggerDoc("v1", new Info
 8                 {
 9                     Version = "v1.1.0",
10                     Title = " WebAPI",
11                    
12                 });
13                 //添加读取注释服务
14                 var basePath = PlatformServices.Default.Application.ApplicationBasePath;
15                 //项目属性 XML的配置名称  APIHelp.xml
16                 var xmlPath = Path.Combine(basePath, "APIHelper.XML"); 
17                 s.IncludeXmlComments(xmlPath);
18  
19                 //添加对控制器的标签(描述)
20                 s.DocumentFilter();
21             });
22             #endregion
23         }
24  

 

结果如下图：

 

2.4 实体类注释

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

  

public class Student
    {
        /// 

        /// 姓名
        /// 
        public string Name { get; set; }
        /// 

        /// 年龄
        /// 
        public int Age { get; set; }
    }

 

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

 

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

 

(2)读取实体类库的XML

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

   

 1 public void ConfigureServices(IServiceCollection services)
 2         {
 3             services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
 4             #region Swagger
 5             services.AddSwaggerGen(s =>
 6             {
 7                 s.SwaggerDoc("v1", new Info
 8                 {
 9                     Version = "v1.1.0",
10                     Title = " WebAPI", 
11                    
12                 });
13                 //添加读取注释服务
14                 var basePath = PlatformServices.Default.Application.ApplicationBasePath;
15                 //项目属性 XML的配置名称  APIHelp.xml
16                 var xmlPath = Path.Combine(basePath, "APIHelper.XML");
17                 var entityXmlPath = Path.Combine(basePath, "CWIOS.Entity.xml");
18                 s.IncludeXmlComments(xmlPath,true);
19                 //添加实体层注释
20                 s.IncludeXmlComments(entityXmlPath);
21                 //添加对控制器的标签(描述)
22                 s.DocumentFilter();
23             });
24             #endregion
25         }
26  

 

新增AddStudent 接口：

 1   /// 

 2         /// 新增学生
 3         /// 
 4         /// 学生实体类
 5         [HttpPost("AddStudent")]
 6         public ActionResult AddStudent(Student student)
 7         {
 8             return Ok("成功");
 9         }
10  

 

最终效果如下图所示：

 

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