.NET Core 使用Swagger给Web API分组

本次使用的代码为.NET Core 3.1

-------------------------------------------------正文开始--------------------------------------------------------------------

创建一个.NET Core Web API项目

项目命名为SwaggerGroup

项目依次添加Swashbuckle.AspNetCore.Swagger、Swashbuckle.AspNetCore.SwaggerGen、Swashbuckle.AspNetCore.SwaggerUI三个swagger配置即可。服务器空间够大的同学，可以直接引用Swashbuckle.AspNetCore（🙄大概144M）

 

 

 

使用swagger分组有两种方式，一种使用json配置，方式更加灵活，两外一种可使用枚举。

NO 1

添加一个如图所示的swagger配置

  "SwaggerConfig": [
    {
      "GroupName": "User",
      "Title": "用户管理",
      "Version": "V1"
    },
    {
      "GroupName": "Sys",
      "Title": "系统管理",
      "Version": "V1"
    }


  ]

新建一个class类

 public class SwaggerConfig
    {
        public string GroupName { get; set; }

        public string Title { get; set; }

        public string Version { get; set; }
    }

修改Startup，添加swagger

 public void ConfigureServices(IServiceCollection services)
        {
            //services.AddControllers();
            //返回的API中文不使用utf-8编码
            services.AddControllers().AddJsonOptions(cfg =>
            {
                cfg.JsonSerializerOptions.Encoder = JavaScriptEncoder.Create(UnicodeRanges.All);
            });
            #region Swagger
            services.AddSwaggerGen(c =>
            {
                var data = Configuration.GetSection("SwaggerConfig").Get<List<SwaggerConfig>>();

                Configuration.GetSection("SwaggerConfig").Get<List<SwaggerConfig>>().ForEach(group =>
                {
                    c.SwaggerDoc(group.GroupName, new OpenApiInfo { Title = group.Title, Version = group.Version });
                });
                string basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
                string xmlPath = Path.Combine(basePath, "SwaggerGroup.xml");
                c.IncludeXmlComments(xmlPath, true);
            });
            #endregion


        }

 

  app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                //c.SwaggerEndpoint("/swagger/v1/swagger.json", "Api Document");
                Configuration.GetSection("SwaggerConfig").Get<List<SwaggerConfig>>().ForEach(group =>
                {
                    c.SwaggerEndpoint($"/swagger/{group.GroupName}/swagger.json", group.Title);  //分组显示
                });
            });

 添加两个控制器

需要分组的控制器表头添加此属性即可

 [ApiExplorerSettings(GroupName = "Sys")]

 效果如下：

 完成后，运行代码，可看到此结果

 NO 1

第二种方式，新建一个枚举类型

 public enum OpenApiGroup
    {
        [Description("用户管理")]
        User = 1,
        [Description("系统管理")]
        Sys = 2
    }

修改startup

            #region Swagger 第二种方式
            services.AddSwaggerGen(c =>
            {
                typeof(OpenApiGroup).GetEnumNames().ToList().ForEach(version =>
                {

                    c.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Title = $"{version}:Swagger文档",
                        Version = version,
                        Description = $"Panda.Sewerage :  {version}  "
                    });
                });
                string basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
                string xmlPath = Path.Combine(basePath, "SwaggerGroup.xml");
                c.IncludeXmlComments(xmlPath, true);
            });
            #endregion

 #region Swagger分组第二种
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                //c.SwaggerEndpoint("/swagger/v1/swagger.json", "Api Document");
                typeof(OpenApiGroup).GetEnumNames().ToList().ForEach(version =>
                {
                    c.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"{version}");
                });
            });
            #endregion

控制器使用方式和第一种类似

本文代码下载地址：点击下载