msumshk/TakeoutSaaS.AdminApi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: 修复文件上传Swagger生成并加载中文注释

Browse Source
This commit is contained in:
MSuMshk
2025-12-04 20:18:26 +08:00
parent 1d7836a173
commit ba9be6bbc4
9 changed files with 93 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
src/Api/Directory.Build.props Normal file
View File

@@ -0,0 +1,5 @@
<Project>
<ItemGroup>
<Using Include="Asp.Versioning" />
</ItemGroup>
</Project>

20
src/Api/TakeoutSaaS.AdminApi/Contracts/Requests/FileUploadFormRequest.cs Normal file
View File

@@ -0,0 +1,20 @@
using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Http;
namespace TakeoutSaaS.AdminApi.Contracts.Requests;
/// <summary>
/// 文件上传表单请求。
/// </summary>
public sealed record FileUploadFormRequest
{
/// <summary>
/// 上传文件。
/// </summary>
[Required]
public required IFormFile File { get; init; }
/// <summary>
/// 上传类型。
/// </summary>
public string? Type { get; init; }
}

16
src/Api/TakeoutSaaS.AdminApi/Controllers/FilesController.cs
View File

@@ -1,5 +1,6 @@
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using TakeoutSaaS.AdminApi.Contracts.Requests;
using TakeoutSaaS.Application.Storage.Abstractions;
using TakeoutSaaS.Application.Storage.Contracts;
using TakeoutSaaS.Application.Storage.Extensions;
@@ -22,32 +23,29 @@ public sealed class FilesController(IFileStorageService fileStorageService) : Ba
/// </summary>
/// <returns>文件上传响应信息。</returns>
[HttpPost("upload")]
[Consumes("multipart/form-data")]
[RequestFormLimits(MultipartBodyLengthLimit = 30 * 1024 * 1024)]
[ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status400BadRequest)]
public async Task<ApiResponse<FileUploadResponse>> Upload([FromForm] IFormFile? file, [FromForm] string? type, CancellationToken cancellationToken)
public async Task<ApiResponse<FileUploadResponse>> Upload([FromForm] FileUploadFormRequest request, CancellationToken cancellationToken)
{
// 1. 校验文件有效性
if (file == null || file.Length == 0)
if (request.File is null || request.File.Length == 0)
{
return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "文件不能为空");
}
// 2. 解析上传类型
if (!UploadFileTypeParser.TryParse(type, out var uploadType))
if (!UploadFileTypeParser.TryParse(request.Type, out var uploadType))
{
return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "上传类型不合法");
}
// 3. 提取请求来源
var origin = Request.Headers["Origin"].FirstOrDefault() ?? Request.Headers["Referer"].FirstOrDefault();
await using var stream = file.OpenReadStream();
await using var stream = request.File.OpenReadStream();
// 4. 调用存储服务执行上传
var result = await fileStorageService.UploadAsync(
new UploadFileRequest(uploadType, stream, file.FileName, file.ContentType ?? string.Empty, file.Length, origin),
new UploadFileRequest(uploadType, stream, request.File.FileName, request.File.ContentType ?? string.Empty, request.File.Length, origin),
cancellationToken);
// 5. 返回上传结果
return ApiResponse<FileUploadResponse>.Ok(result);
}

20
src/Api/TakeoutSaaS.MiniApi/Contracts/Requests/FileUploadFormRequest.cs Normal file
View File

@@ -0,0 +1,20 @@
using System.ComponentModel.DataAnnotations;
using Microsoft.AspNetCore.Http;
namespace TakeoutSaaS.MiniApi.Contracts.Requests;
/// <summary>
/// 文件上传表单请求。
/// </summary>
public sealed record FileUploadFormRequest
{
/// <summary>
/// 上传文件。
/// </summary>
[Required]
public required IFormFile File { get; init; }
/// <summary>
/// 上传类型。
/// </summary>
public string? Type { get; init; }
}

19
src/Api/TakeoutSaaS.MiniApi/Controllers/FilesController.cs
View File

@@ -6,6 +6,7 @@ using TakeoutSaaS.Application.Storage.Extensions;
using TakeoutSaaS.Shared.Abstractions.Constants;
using TakeoutSaaS.Shared.Abstractions.Results;
using TakeoutSaaS.Shared.Web.Api;
using TakeoutSaaS.MiniApi.Contracts.Requests;
namespace TakeoutSaaS.MiniApi.Controllers;
@@ -20,37 +21,33 @@ public sealed class FilesController(IFileStorageService fileStorageService) : Ba
/// <summary>
/// 上传图片或文件。
/// </summary>
/// <param name="file">上传文件。</param>
/// <param name="type">上传类型。</param>
/// <param name="request">表单请求，包含文件与类型。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>上传结果，包含访问链接等信息。</returns>
[HttpPost("upload")]
[Consumes("multipart/form-data")]
[RequestFormLimits(MultipartBodyLengthLimit = 30 * 1024 * 1024)]
[ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ApiResponse<FileUploadResponse>), StatusCodes.Status400BadRequest)]
public async Task<ApiResponse<FileUploadResponse>> Upload([FromForm] IFormFile? file, [FromForm] string? type, CancellationToken cancellationToken)
public async Task<ApiResponse<FileUploadResponse>> Upload([FromForm] FileUploadFormRequest request, CancellationToken cancellationToken)
{
// 1. 校验文件有效性
if (file == null || file.Length == 0)
if (request.File is null || request.File.Length == 0)
{
return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "文件不能为空");
}
// 2. 解析上传类型
if (!UploadFileTypeParser.TryParse(type, out var uploadType))
if (!UploadFileTypeParser.TryParse(request.Type, out var uploadType))
{
return ApiResponse<FileUploadResponse>.Error(ErrorCodes.BadRequest, "上传类型不合法");
}
// 3. 提取请求来源
var origin = Request.Headers["Origin"].FirstOrDefault() ?? Request.Headers["Referer"].FirstOrDefault();
await using var stream = file.OpenReadStream();
await using var stream = request.File.OpenReadStream();
// 4. 调用存储服务执行上传
var result = await fileStorageService.UploadAsync(
new UploadFileRequest(uploadType, stream, file.FileName, file.ContentType ?? string.Empty, file.Length, origin),
new UploadFileRequest(uploadType, stream, request.File.FileName, request.File.ContentType ?? string.Empty, request.File.Length, origin),
cancellationToken);
// 5. 返回上传结果
return ApiResponse<FileUploadResponse>.Ok(result);
}

18
src/Core/TakeoutSaaS.Shared.Web/Extensions/ServiceCollectionExtensions.cs
View File

@@ -1,9 +1,10 @@
using Asp.Versioning;
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using TakeoutSaaS.Shared.Abstractions.Security;
using TakeoutSaaS.Shared.Web.Filters;
using TakeoutSaaS.Shared.Web.Security;
namespace TakeoutSaaS.Shared.Web.Extensions;
/// <summary>
@@ -16,10 +17,11 @@ public static class ServiceCollectionExtensions
/// </summary>
public static IServiceCollection AddSharedWebCore(this IServiceCollection services)
{
// 1. 注册基础上下文与当前用户访问器
services.AddHttpContextAccessor();
services.AddEndpointsApiExplorer();
services.AddScoped<ICurrentUserAccessor, HttpContextCurrentUserAccessor>();
// 2. 注册控制器与全局过滤器
services
.AddControllers(options =>
{
@@ -27,25 +29,25 @@ public static class ServiceCollectionExtensions
options.Filters.Add<ApiResponseResultFilter>();
})
.AddNewtonsoftJson();
// 3. 配置模型验证行为
services.Configure<ApiBehaviorOptions>(options =>
{
options.SuppressModelStateInvalidFilter = true;
});
services.AddApiVersioning(options =>
// 4. 配置 API 版本化
var apiVersioningBuilder = services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
});
services.AddVersionedApiExplorer(setup =>
// 5. 注册版本化 Api Explorer
apiVersioningBuilder.AddApiExplorer(setup =>
{
setup.GroupNameFormat = "'v'VVV";
setup.SubstituteApiVersionInUrl = true;
});
// 6. 返回服务集合
return services;
}
}

12
src/Core/TakeoutSaaS.Shared.Web/Swagger/ConfigureSwaggerOptions.cs
View File

@@ -1,9 +1,8 @@
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace TakeoutSaaS.Shared.Web.Swagger;
/// <summary>
@@ -15,8 +14,12 @@ internal sealed class ConfigureSwaggerOptions(
{
private readonly SwaggerDocumentSettings _settings = settings.Value;
/// <summary>
/// 根据 API 版本生成 Swagger 文档配置。
/// </summary>
public void Configure(SwaggerGenOptions options)
{
// 1. 为每个 API 版本注册文档
foreach (var description in provider.ApiVersionDescriptions)
{
var info = new OpenApiInfo
@@ -27,14 +30,13 @@ internal sealed class ConfigureSwaggerOptions(
? $"{_settings.Description}（该版本已弃用）"
: _settings.Description
};
options.SwaggerGeneratorOptions.SwaggerDocs[description.GroupName] = info;
}
// 2. 配置 JWT 授权信息
if (_settings.EnableAuthorization)
{
const string bearerSchemeName = "Bearer";
var scheme = new OpenApiSecurityScheme
{
Name = "Authorization",
@@ -44,7 +46,6 @@ internal sealed class ConfigureSwaggerOptions(
Scheme = "bearer",
BearerFormat = "JWT"
};
options.AddSecurityDefinition(bearerSchemeName, scheme);
options.AddSecurityRequirement(document =>
{
@@ -52,7 +53,6 @@ internal sealed class ConfigureSwaggerOptions(
{
{ new OpenApiSecuritySchemeReference(bearerSchemeName, document, null), new List<string>() }
};
return requirement;
});
}

21
src/Core/TakeoutSaaS.Shared.Web/Swagger/SwaggerExtensions.cs
View File

@@ -1,5 +1,7 @@
using System;
using System.IO;
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Options;
@@ -17,7 +19,16 @@ public static class SwaggerExtensions
/// </summary>
public static IServiceCollection AddSharedSwagger(this IServiceCollection services, Action<SwaggerDocumentSettings>? configure = null)
{
services.AddSwaggerGen();
// 1. 注册 Swagger 并加载 XML 注释以展示中文文档
services.AddSwaggerGen(options =>
{
var basePath = AppContext.BaseDirectory;
var xmlFiles = Directory.GetFiles(basePath, "*.xml");
foreach (var xml in xmlFiles)
{
options.IncludeXmlComments(xml, true);
}
});
services.AddSingleton(_ =>
{
var settings = new SwaggerDocumentSettings();
@@ -28,7 +39,6 @@ public static class SwaggerExtensions
new ConfigureSwaggerOptions(
provider.GetRequiredService<IApiVersionDescriptionProvider>(),
Options.Create(provider.GetRequiredService<SwaggerDocumentSettings>())));
return services;
}
@@ -39,7 +49,7 @@ public static class SwaggerExtensions
{
var provider = app.ApplicationServices.GetRequiredService<IApiVersionDescriptionProvider>();
var settings = app.ApplicationServices.GetRequiredService<SwaggerDocumentSettings>();
// 1. 注册 Swagger 中间件
app.UseSwagger();
app.UseSwaggerUI(options =>
{
@@ -49,10 +59,9 @@ public static class SwaggerExtensions
$"/swagger/{description.GroupName}/swagger.json",
$"{settings.Title} {description.ApiVersion}");
}
// 2. 显示请求耗时
options.DisplayRequestDuration();
});
return app;
}
}

5
src/Core/TakeoutSaaS.Shared.Web/TakeoutSaaS.Shared.Web.csproj
View File

@@ -9,13 +9,12 @@
</ItemGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="5.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer" Version="5.1.0" />
<PackageReference Include="Asp.Versioning.Mvc" Version="8.1.0" />
<PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.1.0" />
<PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="10.0.0" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="10.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="10.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.1" />
<PackageReference Include="Microsoft.OpenApi" Version="3.0.1" />
</ItemGroup>
<ItemGroup>