.NET Core 2.2 版本使用Swagger Core 版本初探

写在前面

在全新的.NET Core 版本中我们熟悉的Swagger也迎来了全新的Core版本，在这里我将记录下搭建并完善Swagger的全部过程，其中有部分内容参考了相关资料在此附上链接。https://www.cnblogs.com/RayWang/p/9216820.html

准备工作

1. 创建一个.NET Core WebApi 项目
2. 创建一个Model类库
3. 在WebApi中引入Swashbuckle.AspNetCore

正式开始

基础建设：

1.在WebApi项目中执行命令：Install-package Swashbuckle.AspNetCore

2.在StarUp.cs的ConfigureServices中添加代码

#region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "启梦框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
            });
 #endregion

3. 在StarUp.cs的Configure中添加代码

#region Swagger
app.UseSwagger();
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "ApiHelp V1");
});
#endregion

4.运行后进入/swagger目录 即可查看Swagger已经启用

5.如果需要将WebApi的默认启动页设为Swagger则在Properties中

完善工作1，完善注释配置 

在这里大家会发现运行后接口的注释并没有显示，我们需要配置注释XML文件

1.首先在WebAPI项目上点击右键-》属性-》生成-》XML文档文件

2.在StartUp中Swagger配置加入XML文件

 #region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "启梦框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                //添加接口XML的路径
                var xmlPath = Path.Combine(basePath, "TrySwaggerCore.xml");
                //如果需要显示控制器注释只需将第二个参数设置为true
                c.IncludeXmlComments(xmlPath, true);
            });
            #endregion

3.运行后Swagger中就有了相关注释

4.此时大家会发现有了许多警告，强迫症患者看这里，我们只需要在生成中强制过滤1591的警告即可

5.切记此处代码第二个参数需要设置为True，否则将不显示控制器级别的注释，只显示接口注释

完善2，当注释存在于其它项目实体时我们无法查看其它实体的注释

现在很多时候我们需要用到仓储模式对模型进行封装，所以我们需要对某些存在于其它项目的实体进行注释时应该怎么办呢？

以此项目为例，我需要使用的实体处于Model中，则我们需要在Model的属性-》生成-》XML文件中添加一个XML文件，注意保证该文件目录在WebAPI中而不是Model中之后在StartUp中添加以下代码

#region Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1.1.0",
                    Title = "QMFrameWork WebAPI",
                    Description = "启梦框架",
                    TermsOfService = "None",
                    Contact = new Swashbuckle.AspNetCore.Swagger.Contact { Name = "QMFrameWork", Email = "[email protected]", Url = "https://blog.csdn.net/weixin_42550800" }
                });
                // 为 Swagger JSON and UI设置xml文档注释路径
                var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                //添加接口XML的路径
                var xmlPath = Path.Combine(basePath, "TrySwaggerCore.xml");
                //定义实体类XML的路径
                var entityXmlPath = Path.Combine(basePath, "Model.xml");
                //如果需要显示控制器注释只需将第二个参数设置为true
                c.IncludeXmlComments(xmlPath, true);
                //添加实体的注释
                c.IncludeXmlComments(entityXmlPath);
            });
            #endregion

        }

至此一个较为完善的Swagger Core就搭建完成了