ASP.NET Core 3.1使用Swagger

一、什么是Swagger

随着技术的不断方法，现在的网站开发基本都是使用前后端分离的模式，这样使前端开发者和后端开发者只需要专注自己擅长的即可。但这种方式会存在一种问题：前后端通过API接口的方式进行调用，接口文档的好坏可以决定开发的进度。以前如果使用Word的形式提供接口文档，或多或少的都会存在各种问题。前端抱怨说后端给的接口文档与实际情况不一致。而后端开发人员又觉得编写以及维护接口文档很费精力，文档经常不能及时更新，导致前端看到的还是旧的接口文档。这时候就需要使用Swagger了。

那么什么是Swagger呢？Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。

有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/

二、ASP.NET Core中使用Swagger

直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装：

在Startup类的ConfigureServices方法里面注入服务：

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddSwaggerGen(s =>
            {
                s.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
            });
        }

添加中间件

  app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
            });

这样就可以看到接口了。但这样还不是我们最终想要的结果，我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。首先安装Microsoft.Extensions.PlatformAbstractions包：

swagger提示缺少对公共可见类型或成员

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddTransient<ITouristRouteService, TouristRouteService>();
            services.AddDbContext<AppDbContext>(options =>
            {
                options.UseSqlServer(Configuration.GetConnectionString("DBURL"));
            });

            // 添加Swagger
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });

                // 获取xml文件名
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                // 获取xml文件路径
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 添加控制器层注释，true表示显示控制器注释
                c.IncludeXmlComments(xmlPath, true);

            });
            services.AddControllers();
            services.AddAutoMapper(AppDomain.CurrentDomain.GetAssemblies());
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            // 添加Swagger有关中间件
            app.UseSwagger();
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");

            });
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }