Asp.Net Core3.1 Swagger简单使用

一、Nuget安装Swashbuckle.AspNetCore

二、Startup 注册Swagger服务

  //Register the Swagger generator, defining 1 or more Swagger documents   注册Swagger生成器,定义由Swagger生成器创建的一个或多个文档
            services.AddSwaggerGen(s =>
            {
                //定义由Swagger生成器创建的一个或多个文档
                s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = "Swagger测试",
                    Description = "这是一个swagger测试接口",
                    Version = "v1",
                    TermsOfService = new Uri("https://test.com"), // A URL to the Terms of Service for the API. MUST be in the format of a URL.   API服务条款的URL

                    Contact = new Microsoft.OpenApi.Models.OpenApiContact()
                    {
                        Email = "shanshanyouwen@126.com",
                        Name = "shanshanyouwen"
                    },
                    License = new Microsoft.OpenApi.Models.OpenApiLicense()
                    {

                        Name = "SwaggerLicense",
                        Url = new Uri("https://test.com")
                    }
                });
              
            });

三、使用swagger中间件

   // Enable middleware to serve generated Swagger as a JSON endpoint. 允许中间件将生成的Swagger用作JSON端点。
            // Register the Swagger middleware with optional setup action for DI-injected options 使用DI注入选项的可选设置操作注册Swagger中间件 
            app.UseSwagger();

            //Register the SwaggerUI middleware with optional setup action for DI-injected  为注入的DI注册带有可选设置操作的SwaggerUI中间件
            //Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.) 使中间件能够为swagger ui（HTML、JS、CSS等）提供服务
            app.UseSwaggerUI();

四、启动项目

访问地址：http://localhost:44573/swagger/

五、配置XML注释

在visual studio 解决方案管理器窗口选中项目右键选中编辑项目文件

在配置参数上添加以下配置

 <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn> 

在Startup里的服务注册中添加XML的文件路径设置

 //Register the Swagger generator, defining 1 or more Swagger documents   注册Swagger生成器,定义由Swagger生成器创建的一个或多个文档
            services.AddSwaggerGen(s =>
            {
                //定义由Swagger生成器创建的一个或多个文档
                s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo()
                {
                    Title = "Swagger测试接口",
                    Description = "这是一个swagger测试接口",
                    Version = "v1",
                    TermsOfService = new Uri("https://test.com"), // A URL to the Terms of Service for the API. MUST be in the format of a URL.   API服务条款的URL

                    Contact = new Microsoft.OpenApi.Models.OpenApiContact()
                    {
                        Email = "shanshanyouwen@126.com",
                        Name = "shanshanyouwen"
                    },
                    License = new Microsoft.OpenApi.Models.OpenApiLicense()
                    {

                        Name = "SwaggerLicense",
                        Url = new Uri("https://test.com")
                    }
                });

                //将 Swagger 配置为使用按照上述说明生成的 XML 文件。 对于 Linux 或非 Windows 操作系统，文件名和路径区分大小写。 例如，TodoApi.XML 文件在 Windows 上有效，但在 CentOS 上无效。
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // AppContext.BaseDirectory属性用于构造 XML 文件的路径。 一些 Swagger 功能（例如，输入参数的架构，或各自属性中的 HTTP 方法和响应代码）无需使用 XML 文档文件即可起作用。 对于大多数功能（即方法摘要以及参数说明和响应代码说明），必须使用 XML 文件。
                s.IncludeXmlComments(xmlPath);
            });

在接口方法上添加注释说明，如下

    /// <summary>
        /// Get weatherforecast info
        /// </summary>
        /// <param name="day">获取几天的信息</param>
        /// <remarks>
        /// day:设置获取几天天气信息
        /// </remarks>
        /// <returns></returns>
        [HttpGet] 
        public IEnumerable<WeatherForecast> Get(int day)
        {
            var rng = new Random();
            return Enumerable.Range(1, day).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = rng.Next(-20, 55),
                Summary = Summaries[rng.Next(Summaries.Length)]
            })
            .ToArray();
        }

六、再次启动项目

参考网址：Swashbuckle 和 ASP.NET Core 入门 | Microsoft Learn