开始整理Setup.cs

SwaggerStudy/Program.cs

@@ -21,10 +21,19 @@ namespace SwaggerStudy
             Host.CreateDefaultBuilder(args)
                 .ConfigureWebHostDefaults(webBuilder =>
                 {
-                    webBuilder.UseStartup<StartupTest>();
+                    //测试 Swagger 设置
+                    //webBuilder.UseStartup<StartupTest>();
+
+                    //不使用 Swagger
                     //webBuilder.UseStartup<Startup>();
+
+                    //简单引入Swagger
                     //webBuilder.UseStartup<Startup01>();
-                    //webBuilder.UseStartup<Startup02>();
+
+                    //启用xml注释
+                    webBuilder.UseStartup<Startup02>();
+
+
                     //webBuilder.UseStartup<Startup03>();
                     //webBuilder.UseStartup<Startup04>();
                     //webBuilder.UseStartup<Startup05>();

SwaggerStudy/Startup.cs

@@ -11,19 +11,13 @@ using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
 
-using Swashbuckle;
-using Swashbuckle.AspNetCore.Swagger;
-using Swashbuckle.AspNetCore.SwaggerGen;
-using Swashbuckle.AspNetCore.SwaggerUI;
-
 
 using SwaggerStudy.Services;
-using Microsoft.OpenApi.Models;
 
 namespace SwaggerStudy
 {
     /// <summary>
-    /// 未引入Swagger
+    /// 不使用 Swagger
     /// </summary>
     public class Startup
     {
@@ -38,11 +32,16 @@ namespace SwaggerStudy
         {
             services
                 .AddControllers()
+                //配置System.Text.Json选项
                 .AddJsonOptions(jsonOption=> 
                 {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
                     jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
                     jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
                     jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
+                    //转义字符串编码器：直接显示中文
                     jsonOption.JsonSerializerOptions.Encoder= System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
                 });
 

SwaggerStudy/Startup01.cs

@@ -10,6 +10,7 @@ using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
+using Microsoft.OpenApi.Models;
 
 using Swashbuckle;
 using Swashbuckle.AspNetCore.Swagger;
@@ -18,12 +19,17 @@ using Swashbuckle.AspNetCore.SwaggerUI;
 
 
 using SwaggerStudy.Services;
-using Microsoft.OpenApi.Models;
 
 namespace SwaggerStudy
 {
     /// <summary>
     /// 简单引入Swagger
+    /// 1、使用Nuget包管理器，引用 Swashbuckle.AspNetCore 库
+    /// 2、引入命名空间：Microsoft.OpenApi.Models
+    /// 3、在 Startup.cs 的 ConfigureServices 方法中，注册 Swagger 生成器，定义一个或多个 Swagger 文档。
+    /// 4、在 Startup.cs 的 Configure 方法中，启用 Swagger中间件
+    /// 5、在 Startup.cs 的 Configure 方法中，启用 Swagger UI中间件，指定 Swagger JSON 端点以便从中启动它
+    /// 6、确保 WebAPI Action和parameters  使用显式的""HttpXX" and "FromXX"绑定进行修饰
     /// </summary>
     public class Startup01
     {
@@ -38,17 +44,28 @@ namespace SwaggerStudy
         {
             services
                 .AddControllers()
-                .AddJsonOptions(jsonOption=> 
+                //配置System.Text.Json选项
+                .AddJsonOptions(jsonOption =>
                 {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
+                    jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
+                    jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
                     jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
-                    jsonOption.JsonSerializerOptions.Encoder= System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
+                    //转义字符串编码器：直接显示中文
+                    jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
                 });
-            #region swagger
+
+            //注册Swagger生成器，定义一个或多个 Swagger 文档
             services.AddSwaggerGen(setup =>
             {
-                setup.SwaggerDoc("GroupA", new OpenApiInfo { Title = "Swagger学习",  Version = "第一版" });
+                #region 定义Swagger文档
+                //name参数即为SwaggerUI中SwaggerEndpoint方法参数中的{documentName}
+                //两者必须保持一致，否则异常
+                setup.SwaggerDoc(name: "v1", new OpenApiInfo { Title = "Swagger学习", Version = "第一版" });
+                #endregion
             });
-            #endregion
 
             services.AddTransient<StudentServer>();
         }
@@ -60,11 +77,20 @@ namespace SwaggerStudy
                 app.UseDeveloperExceptionPage();
             }
 
-            app.UseSwagger();
-            app.UseSwaggerUI(setup => 
-            { 
-                setup.SwaggerEndpoint("/swagger/GroupA/swagger.json", "Swagger学习第一版");
-                
+            //启用 Swagger 中间件
+            app.UseSwagger(setup =>
+            {
+
+            });
+
+            //启用 SwaggerUI 中间件
+            app.UseSwaggerUI(setup =>
+            {
+                #region 添加Swagger JSON端点
+                //必须包含{documentName}即是SwaggerDoc的name参数. 
+                //默认为/swagger/{documentName}/swagger.json
+                setup.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger学习第一版");
+                #endregion
             });
 
             app.UseRouting();

SwaggerStudy/Startup02.cs

@@ -10,6 +10,7 @@ using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
+using Microsoft.OpenApi.Models;
 
 using Swashbuckle;
 using Swashbuckle.AspNetCore.Swagger;
@@ -18,12 +19,17 @@ using Swashbuckle.AspNetCore.SwaggerUI;
 
 
 using SwaggerStudy.Services;
-using Microsoft.OpenApi.Models;
 
 namespace SwaggerStudy
 {
     /// <summary>
-    /// 使用Swagger UI
+    /// 启用xml注释
+    /// 1、打开项目文件xx.csproj，PropertyGroup节点内添加
+    ///    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    ///    <NoWarn>$(NoWarn);1591</NoWarn>
+    /// 2、Startup.cs的ConfigureServices方法中的services.AddSwaggerGen里，用setup.IncludeXmlComments()所有项目xml注释文件
+    /// 3、WebApi方法与控制器中，使用xml注释
+    /// 4、重新编译后使用
     /// </summary>
     public class Startup02
     {
@@ -38,12 +44,38 @@ namespace SwaggerStudy
         {
             services
                 .AddControllers()
-                .AddJsonOptions(jsonOption=> 
+                //配置System.Text.Json选项
+                .AddJsonOptions(jsonOption =>
                 {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
+                    jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
+                    jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
                     jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
-                    jsonOption.JsonSerializerOptions.Encoder= System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
+                    //转义字符串编码器：直接显示中文
+                    jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
                 });
 
+            //注册Swagger生成器，定义一个或多个 Swagger 文档
+            services.AddSwaggerGen(setup =>
+            {
+                #region 定义Swagger文档
+                //name参数即为SwaggerUI中SwaggerEndpoint方法参数中的{documentName}
+                //两者必须保持一致，否则异常
+                setup.SwaggerDoc(name: "v1", new OpenApiInfo { Title = "Swagger学习", Version = "第一版" });
+                #endregion
+
+                #region 包含xml注释
+                var xmlCommentFiles = System.IO.Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, $"SwaggerStudy*.xml", System.IO.SearchOption.TopDirectoryOnly);
+                foreach (var xmlFile in xmlCommentFiles)
+                {
+                    //includeControllerXmlComments参数：是否启用控制器上的xml注释
+                    setup.IncludeXmlComments(filePath: xmlFile, includeControllerXmlComments: true);
+                }
+                #endregion
+            });
+
             services.AddTransient<StudentServer>();
         }
 
@@ -54,6 +86,22 @@ namespace SwaggerStudy
                 app.UseDeveloperExceptionPage();
             }
 
+            //启用 Swagger 中间件
+            app.UseSwagger(setup=>
+            { 
+ 
+            });
+
+            //启用 SwaggerUI 中间件
+            app.UseSwaggerUI(setup => 
+            {
+                #region 添加Swagger JSON端点
+                //必须包含{documentName}即是SwaggerDoc的name参数. 
+                //默认为/swagger/{documentName}/swagger.json
+                setup.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger学习第一版");
+                #endregion
+            });
+
             app.UseRouting();
 
             app.UseAuthorization();

SwaggerStudy/Startup031.cs

@@ -0,0 +1,113 @@
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using System.Collections.Generic;
+
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+using Swashbuckle;
+using Swashbuckle.AspNetCore.Swagger;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Swashbuckle.AspNetCore.SwaggerUI;
+
+
+using SwaggerStudy.Services;
+using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Any;
+
+namespace SwaggerStudy
+{
+    /// <summary>
+    /// 默认System.Text.Json序列化库
+    /// </summary>
+    public class Startup031
+    {
+        public Startup031(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services
+                .AddControllers()
+                //配置System.Text.Json选项
+                .AddJsonOptions(jsonOption =>
+                {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
+                    jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
+                    jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
+                    jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
+                    //转义字符串编码器：直接显示中文
+                    jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
+                });
+
+            services.AddTransient<StudentServer>();
+
+            //注册Swagger生成器，定义一个或多个 Swagger 文档
+            services.AddSwaggerGen(setup =>
+            {
+                #region 定义Swagger文档
+                //name参数即为SwaggerUI中SwaggerEndpoint方法参数中的{documentName}
+                //两者必须保持一致，否则异常
+                setup.SwaggerDoc(name: "v1", new OpenApiInfo { Title = "Swagger学习", Version = "第一版" });
+                #endregion
+
+                #region 包含xml注释
+                var xmlCommentFiles = System.IO.Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, $"SwaggerStudy*.xml", System.IO.SearchOption.TopDirectoryOnly);
+                foreach (var xmlFile in xmlCommentFiles)
+                {
+                    //includeControllerXmlComments参数：是否启用控制器上的xml注释
+                    setup.IncludeXmlComments(filePath: xmlFile, includeControllerXmlComments: true);
+                }
+                #endregion
+
+                //默认使用 System.Text.Json
+            });
+        }
+
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+
+            //启用 Swagger 中间件
+            app.UseSwagger(setup =>
+            {
+
+            });
+
+            //启用 SwaggerUI 中间件
+            app.UseSwaggerUI(setup =>
+            {
+                #region 添加Swagger JSON端点
+                //必须包含{documentName}即是SwaggerDoc的name参数. 
+                //默认为/swagger/{documentName}/swagger.json
+                setup.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger学习第一版");
+                #endregion
+            });
+
+            app.UseRouting();
+
+            app.UseAuthorization();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapControllers();
+            });
+        }
+    }
+}

SwaggerStudy/Startup032.cs

@@ -0,0 +1,109 @@
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+using System.Collections.Generic;
+
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+using Swashbuckle;
+using Swashbuckle.AspNetCore.Swagger;
+using Swashbuckle.AspNetCore.SwaggerGen;
+using Swashbuckle.AspNetCore.SwaggerUI;
+
+
+using SwaggerStudy.Services;
+using Microsoft.OpenApi.Models;
+
+namespace SwaggerStudy
+{
+    /// <summary>
+    /// 使用Newtonsoft替代默认System.Text.Json序列化库
+    /// </summary>
+    public class Startup032
+    {
+        public Startup032(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+        public void ConfigureServices(IServiceCollection services)
+        {
+            services
+                .AddControllers()
+                //配置System.Text.Json选项
+                .AddJsonOptions(jsonOption =>
+                {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
+                    jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
+                    jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
+                    jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
+                    //转义字符串编码器：直接显示中文
+                    jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
+                });
+
+            //注册Swagger生成器，定义一个或多个 Swagger 文档
+            services.AddSwaggerGen(setup =>
+            {
+                #region 定义Swagger文档
+                //name参数即为SwaggerUI中SwaggerEndpoint方法参数中的{documentName}
+                //两者必须保持一致，否则异常
+                setup.SwaggerDoc(name: "v1", new OpenApiInfo { Title = "Swagger学习", Version = "第一版" });
+                #endregion
+
+                #region 包含xml注释
+                var xmlCommentFiles = System.IO.Directory.GetFiles(AppDomain.CurrentDomain.BaseDirectory, $"SwaggerStudy*.xml", System.IO.SearchOption.TopDirectoryOnly);
+                foreach (var xmlFile in xmlCommentFiles)
+                {
+                    //includeControllerXmlComments参数：是否启用控制器上的xml注释
+                    setup.IncludeXmlComments(filePath: xmlFile, includeControllerXmlComments: true);
+                }
+                #endregion
+            });
+
+            services.AddTransient<StudentServer>();
+        }
+
+        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+
+            //启用 Swagger 中间件
+            app.UseSwagger(setup =>
+            {
+
+            });
+
+            //启用 SwaggerUI 中间件
+            app.UseSwaggerUI(setup =>
+            {
+                #region 添加Swagger JSON端点
+                //必须包含{documentName}即是SwaggerDoc的name参数. 
+                //默认为/swagger/{documentName}/swagger.json
+                setup.SwaggerEndpoint("/swagger/v1/swagger.json", "Swagger学习第一版");
+                #endregion
+            });
+
+            app.UseRouting();
+
+            app.UseAuthorization();
+
+            app.UseEndpoints(endpoints =>
+            {
+                endpoints.MapControllers();
+            });
+        }
+    }
+}

SwaggerStudy/StartupTest.cs

@@ -10,16 +10,18 @@ using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using Microsoft.Extensions.Logging;
+
 using Microsoft.OpenApi.Models;
+using Microsoft.OpenApi.Interfaces;
+using Microsoft.OpenApi.Any;
 
 using Swashbuckle;
+using Swashbuckle.AspNetCore;
 using Swashbuckle.AspNetCore.Swagger;
 using Swashbuckle.AspNetCore.SwaggerGen;
 using Swashbuckle.AspNetCore.SwaggerUI;
 
 using SwaggerStudy.Services;
-using Microsoft.OpenApi.Interfaces;
-using Microsoft.OpenApi.Any;
 
 namespace SwaggerStudy
 {
@@ -39,15 +41,20 @@ namespace SwaggerStudy
         {
             services
                 .AddControllers()
+                //配置System.Text.Json选项
                 .AddJsonOptions(jsonOption =>
                 {
+                    //整齐打印：压缩格式(一行)还是整齐格式(换行)
                     jsonOption.JsonSerializerOptions.WriteIndented = true;
+                    //允许(忽略)对象或数据末尾多余的逗号
                     jsonOption.JsonSerializerOptions.AllowTrailingCommas = true;
+                    //自定义时间格式转换器
                     jsonOption.JsonSerializerOptions.Converters.Add(new DatetimeJsonConverter());
+                    //转义字符串编码器：直接显示中文
                     jsonOption.JsonSerializerOptions.Encoder = System.Text.Encodings.Web.JavaScriptEncoder.Create(System.Text.Unicode.UnicodeRanges.All);
                 });
 
-            //注入SwaggerGen
+            //注册Swagger生成器，定义一个或多个 Swagger 文档
             services.AddSwaggerGen(setup =>
             {
                 //注意：name参数即是DocumentName, 在SwaggerUi中有使用，配置的终结点里必须保持一致
@@ -152,6 +159,9 @@ namespace SwaggerStudy
                 //swagger 访问页面前缀：默认swagger
                 //SwaggerUi首页地址：baseUrl+前辍+index.html 默认：/swagger/index.html
                 setup.RoutePrefix = "Swagger";
+
+                //必须包含{documentName}:即是SwaggerDoc的name参数. 
+                //默认为/swagger/{documentName}/swagger.json
                 setup.SwaggerEndpoint("/WebApi/swagger/DemoName/swagger.json", "WebApi 测试版");
             });
 

SwaggerStudy/SwaggerStudy.csproj

@@ -14,6 +14,7 @@
   </ItemGroup>
 
   <ItemGroup>
+    <PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
     <PackageReference Include="Swashbuckle.AspNetCore" Version="5.6.3" />
   </ItemGroup>