ASP.Net Core中使用Swagger

我们先简单介绍下什么是Swagger，主要是用来干嘛？？

在Swagger诞生之前，我们通常在开发接口的过程中，需要前后端共同维护一个接口文档，然后大家按照接口文档的规范进行对接。接口文档俨然成了接口开发过程中不可或缺的一部分，然而对于大部分喜欢敲代码的同志们来说，写文档简直头疼，并且一般项目后期往往会由于疏忽未能及时更新文档，导致代码和接口文档不一致，这中间就有点道不清说不明了。

正是在这种大环境下，Swagger及时出现，解放了前后端开发人员对接口文档的维护压力。Swagger实际上就是一个自动生成规范接口文档的工具，由服务端设计人员调用，我们只需要按照它的格式要求在代码中添加注释即可。

好了，下面我们开始步入正题，如何快速搭建Swagger项目。

首先，我们需要添加.NetCore Web API应用程序。

然后，在项目中添加如下Nuget程序包。

添加Swagger引用之后，在项目中注册并使用Swagger.

首先，注册服务。

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            //注册Swagger服务
            services.AddSwaggerGen(s =>
            {
                //基本信息配置
                s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
                {
                    Version = "v1",
                    Title = "个人测试",
                    Description = "仅供测试使用",
                    Contact = new Microsoft.OpenApi.Models.OpenApiContact { Email = "123@123.com" }
                });
                //包含应用程序对应的Swagger xml文档
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                s.IncludeXmlComments(xmlPath);
            });
        }

对于XML文档，我们还需要在生成时指定xml输出路径。我这里是指定的项目根目录。这里有个禁止显示警告配置：添加了1591（用于解决未添加xml说明的警告）

 

 

 

 然后，我们添加Swagger中间件。

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }
            app.UseHttpsRedirection();
            app.UseMvc();
            //使用Swagger
            app.UseSwagger();
            app.UseSwaggerUI(s =>
            {
                //指定json文件
                s.SwaggerEndpoint("/swagger/v1/swagger.json", "My API");
                //默认前缀swagger  此处去掉前缀 直接根目录访问
                s.RoutePrefix = string.Empty;
            });
        }

这里有个地方大家需要注意下：s.SwaggerEndpoint("/swagger/v1/swagger.json", "My API");指定json文件url的时候，url里面的v1需要和服务注册时：s.SwaggerDoc("v1", "")这里的v1对应一致。

最后，我们只需要在启动项目，在浏览器中输入URL:https://localhost:5001/index.html   端口以项目实际启动的端口为准.

 

 

大家可以看到默认的接口方法中：

 

 这里的“Get方式获取”就是我们在项目接口方法体上添加的xml注释说明。

 

 项目搭建成功啦！！！文中如有描述不对的地方，欢迎各位小伙伴前来交流。