From 45552b1c4293e7478833fc17b6739f0d3efaa878 Mon Sep 17 00:00:00 2001
From: bicijinlian <bicijinlian@163.com>
Date: Thu, 24 Dec 2020 23:40:58 +0800
Subject: [PATCH] =?UTF-8?q?=E5=BC=80=E5=A7=8B=E6=95=B4=E7=90=86Setup.cs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
SwaggerStudy/Program.cs | 13 +++-
SwaggerStudy/Startup.cs | 13 ++--
SwaggerStudy/Startup01.cs | 48 ++++++++++---
SwaggerStudy/Startup02.cs | 56 +++++++++++++--
SwaggerStudy/Startup031.cs | 113 +++++++++++++++++++++++++++++++
SwaggerStudy/Startup032.cs | 109 +++++++++++++++++++++++++++++
SwaggerStudy/StartupTest.cs | 16 ++++-
SwaggerStudy/SwaggerStudy.csproj | 1 +
8 files changed, 342 insertions(+), 27 deletions(-)
create mode 100644 SwaggerStudy/Startup031.cs
create mode 100644 SwaggerStudy/Startup032.cs
diff --git a/SwaggerStudy/Program.cs b/SwaggerStudy/Program.cs
index c7ffe33..be2f424 100644
--- a/SwaggerStudy/Program.cs
+++ b/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>();
diff --git a/SwaggerStudy/Startup.cs b/SwaggerStudy/Startup.cs
index 468ce4b..825de38 100644
--- a/SwaggerStudy/Startup.cs
+++ b/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);
});
diff --git a/SwaggerStudy/Startup01.cs b/SwaggerStudy/Startup01.cs
index b9bce69..50ba183 100644
--- a/SwaggerStudy/Startup01.cs
+++ b/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();
diff --git a/SwaggerStudy/Startup02.cs b/SwaggerStudy/Startup02.cs
index 599ff97..ae299ac 100644
--- a/SwaggerStudy/Startup02.cs
+++ b/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();
diff --git a/SwaggerStudy/Startup031.cs b/SwaggerStudy/Startup031.cs
new file mode 100644
index 0000000..8aae380
--- /dev/null
+++ b/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();
+ });
+ }
+ }
+}
diff --git a/SwaggerStudy/Startup032.cs b/SwaggerStudy/Startup032.cs
new file mode 100644
index 0000000..2e1cbae
--- /dev/null
+++ b/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();
+ });
+ }
+ }
+}
diff --git a/SwaggerStudy/StartupTest.cs b/SwaggerStudy/StartupTest.cs
index 150aa32..578966b 100644
--- a/SwaggerStudy/StartupTest.cs
+++ b/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 测试版");
});
diff --git a/SwaggerStudy/SwaggerStudy.csproj b/SwaggerStudy/SwaggerStudy.csproj
index 819ef67..166c388 100644
--- a/SwaggerStudy/SwaggerStudy.csproj
+++ b/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>