KSO-.NETCore中配置swagger分级

Swagger简介

• 如今，前后端分离已经逐渐成为互联网项目一种标准的开发方式，前端与后端交给不同的人员开发，
  但是项目开发中的沟通成本也随之升高，这部分沟通成本主要在于前端开发人员与后端开发人员对WebAPI接口的沟通，Swagger UI
  就可以很好地解决，它可以动态生成Api接口文档，降低沟通成本，促进项目高效开发。

1 下载依赖

.net5以下的版本 需要下载
Install-Package Swashbuckle.AspNetCore -Version 5.0.0-rc4

net5 与net6 不需要下载，因为本身已经集成了

新建一个枚举类  ApiVersions 
基本代码如下：
public enum ApiVersions
    {
        系统管理 = 1,
        用户管理 = 2,
        V1 = 3,
        V2 = 5,
        V3 = 6, 
    }

2 在Startup=》ConfigureServices里面 增加下面代码

  services.AddSwaggerGen(c =>
            {
                
                typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                {
                    c.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Title = $"{version}:Swagger文档",
                        Version = version,
                        Description = $"Demo.Sewerage :  {version}  "
                    });
                });

                string basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录（绝对，不受工作目录影响，建议采用此方法获取路径）
                string xmlPath = Path.Combine(basePath, "Demo.Web.xml");
                c.IncludeXmlComments(xmlPath, true);

            });

、、、、、、、、、、、、、、错误写法、、、、、、、、、、、、、、、、、、、、、、
我见到一些同学 这样写swagger分层,我真的很服气，要是分个很多层，
是不是要一直这样分下去，写个几十条？？？？，很傻逼的写法，希望大家杜绝
 services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("xxx", new OpenApiInfo { Title = "xxx", Version = "v1" });
                c.SwaggerDoc("xxxxx1", new OpenApiInfo { Title = "xxx1", Version = "v1" });
  
                c.IncludeXmlComments(Path.Combine(System.AppContext.BaseDirectory, "Demo.Web.xml")); 
                 c.DocumentFilter<AnnotationsDocumentFilter>();
                c.DocInclusionPredicate((docName, apiDesc) =>
                {
                    return string.Equals(docName, apiDesc.GroupName, StringComparison.OrdinalIgnoreCase);
                });
            });
、、、、、、、、、、、、、、错误写法、、、、、、、、、、、、、、、、、、、、、、

3 在Startup=》Configure里面 增加下面代码

 app.UseSwaggerUI(c =>
            {
                if (env.IsDevelopment())
                { 
                    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                    {
                        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}");
                    });
                }
                else
                {
                    typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                    {
                        c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}");
                    }); 
                }
            });

3 在WEB层新建个 Demo.Web.xml

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>KSOAdmin.WebApi</name>
    </assembly>
    <members>

		<member name="M:KSOAdmin.WebApi.Controllers.HomeController.Index()">
			<summary>
				用来测试
			</summary>
			<returns>测试数据</returns>
		</member>
		<member name="T:KSOAdmin.WebApi.Controllers.HomeController">
			<summary>
				用来测试
			</summary>
		</member>
		<member name="M:KSOAdmin.WebApi.Controllers.Sys_MenuController.GetRoleMenuAsync()">
			<summary>
				获取角色的菜单
			</summary>
			<returns>返回菜单list</returns>
		</member>
		<member name="T:KSOAdmin.WebApi.Controllers.Sys_MenuController">
			<summary>
				菜单操作
			</summary>
		</member>
    </members>
</doc>

4 在控制器上面增加 特性标签

    [ApiExplorerSettings(GroupName = "系统管理")]

这个时候基本上加完了，但是会打开没有备注，这就很坑了，所以还需要一步

5 swagger上面显示控制器方法备注说明

右键webapi 打开属性取消显示警告

6 已经结束了，这样就实现配置了

在你的项目跑起来的地址后面加 swagger/index.html