.net core 3.1引用 Swagger

.net core 3.1引用 Swagger

文章目录

• 前言
• 一、Swagger是什么？
• 二、使用步骤
• • 1.引入库
  • 2.代码
  • 3.进阶用法
  • 4.接口调试
• 总结

---

前言

目前的项目基本都是前后端分离，API 功能的演变是不可避免的，但维护 API 文档的头痛不是必须的。Swagger 工具将繁重的工作从生成和维护您的 API 文档中解脱出来，确保您的文档随着 API 的发展而保持最新。

---

一、Swagger是什么？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

swagger官网：https://swagger.io

二、使用步骤

本次演示源码上传至gitee
地址：https://gitee.com/huang945617/netcore3—using-swagger

1.引入库

通过“管理NuGet程序包”下载 Swashbuckle.AspNetCore包：

2.代码

编辑 Startup.cs：
1.将swagger生成器添加到ConfigureServices方法中：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            #region Swagger服务
            services.AddSwaggerGen(o =>
            {
                o.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "WebApi",
                    Version = "v1",
                    Contact = new OpenApiContact
                    {
                        Name = "对待丶",
                        Email = string.Empty,
                        Url = new Uri("http://127.0.0.1:5000/swagger/index.html")
                    },
                    Description = "API描述",
                    License = new OpenApiLicense
                    {
                        Name = "对待丶",
                        Url = new Uri("http://127.0.0.1:5000/swagger/index.html")
                    }
                });
            });
            #endregion
        }

2.将swagger中间件添加到Configure方法中：

 			#region Swagger 中间件
            app.UseSwagger();
            app.UseSwaggerUI(o =>
            {
                o.SwaggerEndpoint("/swagger/v1/swagger.json", "WebApi");
            });
             #endregion

添加一个测试控制器：

添加后我们启动项目看下效果：http://localhost:/swagger/index.html

启动后虽然可以正常的浏览，但是我们对方法/参数的注释却无法展示出来，这样明显无法达到我们想要的效果。
接下来我们可通过启用XML来实现注释
方法一：
“解决方案资源管理器”选择项目右键单击->“属性”，设置XML文档文件的路径

方法二：
通过“管理NuGet程序包”下载 Microsoft.Extensions.PlatformAbstractions包

使用以上方法的其中一种后，更改ConfigureServices方法中的AddSwaggerGen

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            #region Swagger服务
            services.AddSwaggerGen(o =>
            {
                o.SwaggerDoc("v1", new OpenApiInfo
                {
                    Title = "WebApi",
                    Version = "v1",
                    Contact = new OpenApiContact
                    {
                        Name = "对待丶",
                        Email = string.Empty,
                        Url = new Uri("http://127.0.0.1:5000/swagger/index.html")
                    },
                    Description = "API描述",
                    License = new OpenApiLicense
                    {
                        Name = "对待丶",
                        Url = new Uri("http://127.0.0.1:5000/swagger/index.html")
                    }
                });
				var assemblyName = Assembly.GetEntryAssembly().GetName().Name;
				//控制器 方法/参数注释
                options.IncludeXmlComments(Path.Combine(AppContext.baseDirectory, $"{assemblyName}.xml"), true);
            });
              
            #endregion
        }

更改后，在启动项目浏览看下效果

这样我们添加的注释就可以全部显示出来了。

3.进阶用法

当项目越来越大时，功能模块也越来越多，全部展示在一个页面，不方便对接人员的查找及阅读，如果我们按照我们对应的功能模块来分组是否会更好呢？接下来简单的修改下
1.新建一个类，里面放的是分组对应模块的信息

  public static class SwaggerApi
    {
        /// 

        /// Swagger分组信息，将进行遍历使用
        /// 
        public static readonly List ApiInfos = new List()
        {
            new SwaggerApiInfo
            {
                UrlPrefix = SwaggerGroupingModel.GROUPNAME_TEST,
                Name = "测试模块",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = "v1",
                    Title = "Api-Test",
                    Description =  "Api-测试模块"
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = SwaggerGroupingModel.GROUPNAME_COMM,
                Name = "公共模块",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = "v1",
                    Title = "WebApi-Comm",
                    Description =  "WebApi-公共模块"
                }
            }
        };

        /// 

        /// 分组信息
        /// 
      	pullic  class SwaggerApiInfo
        {
            /// 

            /// URL前缀
            /// 
            public string UrlPrefix { get; set; }

            /// 

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

            /// 

            /// 
            /// 
            public OpenApiInfo OpenApiInfo { get; set; }
        }
    }

    /// 

    /// Swagerr分组模块
    /// 
    public static class SwaggerGroupingModel
    {
        /// 

        /// 公共数据模块
        /// 
        public const string GROUPNAME_TEST = "test";

        /// 

        /// 公共数据模块
        /// 
        public const string GROUPNAME_COMM = "comm";
    }

2.新建一个swagger的扩展类Extensions

  /// 

    /// Swagger 扩展
    /// 
    public static partial class Extensions
    {
        /// 

        /// 配置自定义Swagger服务
        /// 
        /// 应用程序生成器
        public static IApplicationBuilder UseDefaultSwagger(this IApplicationBuilder builder)
        {
            builder.UseSwagger();
            builder.UseSwaggerUI(options =>
            {
                options.DocExpansion(DocExpansion.None);
                //通过循环将加载信息
                SwaggerApi.ApiInfos.ForEach(x =>
                {
                    options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
                });
               #region 以下参数可自行设置
                // 模型的默认扩展深度，设置为 -1 完全隐藏模型
                options.DefaultModelsExpandDepth(-1);
                // API文档仅展开标记
                options.DocExpansion(DocExpansion.List);
                // API前缀设置为空
                options.RoutePrefix = string.Empty;
                options.documentTitle = "WebApi文档";
                //return;
				#region
            });
            return builder;
        }

        /// 

        /// 初始化Swagger
        /// 
        /// 
        public static void InitSwagger(this IServiceCollection services)
        {
            var assemblyName = Assembly.GetEntryAssembly().GetName().Name;
            //添加Swagger
            services.AddSwaggerGen(options =>
            {
            	//通过循环将加载信息
                SwaggerApi.ApiInfos.ForEach(x =>
                {
                    options.SwaggerDoc(x.UrlPrefix, x.OpenApiInfo);
                });
                //解决相同类名会报错的问题
                options.CustomSchemaIds(type => type.FullName);
                //控制器注释
                options.IncludeXmlComments(Path.Combine(AppContext.baseDirectory, $"{assemblyName}.xml"), true);
            });
        }
    }

3.修改Startup类，通过直接调用swagger的扩展类Extensions来添加服务、中间件

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            #region Swagger服务注入
            
            services.InitSwagger();
            
            #endregion

        }

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            #region Swagger 中间件

            app.UseSwagger();
            app.UseDefaultSwagger();
           
            #endregion 
        }

在创建2个测试控制器，在控制器上添加特性[ApiExplorerSettings("")]，没有添加此特性的控制器默认是在每个分组中都显示

启动在浏览下效果，可以看到，控制器都有按照我们的分组展示出来，这样对接人员可以更加方便的来查看对应的接口。

4.接口调试

Swagger除了可以提供接口文档之外，还可以直接进行调试。
选择接口，点击【Try it out】，如果有参数的情况，编辑参数值，点击【Execute】执行，就可以调试了。

总结

到此，关于Swagger的基本使用就说到这里，希望本文对大家使用Swagger有所帮助，想要了解更多的可以通过官网学习！
最后将本次的代码放在gitee，有需要的朋友可自行下载！
地址：https://gitee.com/huang945617/netcore3—using-swagger