.net Core WebApi中使用Swagger生成API文档简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

1、添加并配置Swagger中间件

1.1 按照以下方式添加SwaggerGen 和SwaggerUI对应的NuGet Packages程序包，添加引用SwaggerGen 程序包。

1.2 添加 SwaggerUI程序包。

2、配置

　　2.1 在Startup.cs 类添加命名空间： using Microsoft.OpenApi.Models;

　　ConfigureServices 方法中添加配置

 1  public void ConfigureServices(IServiceCollection services)
 2         {
 3             services.Configure<IISServerOptions>(options =>
 4             {
 5                 options.MaxRequestBodySize = int.MaxValue;
 6             });
 7 
 8             //:使用Swagger
 9             services.AddSwaggerGen(options =>
10             {
11                 options.SwaggerDoc("v1", new OpenApiInfo { Title = "接口文档", Version = "v1" });
12                 // 解决相同类名会报错的问题
13                 options.CustomSchemaIds(type => type.FullName);
14                 //为Swagger的JSON和UI设置XML注释
15                 var basePath = AppContext.BaseDirectory;
16                 var xmlPath = Path.Combine(basePath, "NetCoreWebApi.xml");
17                 options.IncludeXmlComments(xmlPath, true);
18 
19             });
20 
21             services.AddControllers(options =>
22                 //全局异常过滤器
23                 options.Filters.Add<RequestFilterAttribute>()
24                 
25                 );                                        
26         }

　　2.2 配置Configure属性：在Configure方法中，启动中间件为生成的JSON文档和Swagger UI提供服务

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseSwagger();
         
            app.UseSwaggerUI(c =>
            {
                c.InjectJavascript("/swagger/ui/zh_CN.js");
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "接口文档");
            });

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            //将日志记录到数据库
            NLog.LogManager.LoadConfiguration("nlog.config").GetCurrentClassLogger();
            //指定数据库连接
            NLog.LogManager.Configuration.Variables["connectionString"] = Configuration.GetConnectionString("OFCSDBConStr");

            //避免日志中的中文输出乱码
            Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

            //:路由配置
            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }

　3、配置项目属性

4、配置文档Url地址

接口代码

 1  /// <summary>
 2         /// 获取人员信息
 3         /// </summary>
 4         /// <param name="request"></param>
 5         /// <returns></returns>
 6         [HttpPost]
 7         public ActionResult QuerySysMembersInformation(ElearningSysMembersRequestModel request)
 8         {
 9             string guid = Guid.NewGuid().ToString();
10             try
11             {
12                 var List = new ElearningSysMembersRequestModel { UserName = "Aek Ampimai", HRID = "01800023", Dept = "CBS" };
13                 return new JsonResult(List);
14             }
15             catch (Exception ex)
16             {
17                 throw ex;
18 
19             }
20             finally
21             {
22 
23             }
24         }