在 AWS Lambda 上托管 Scalar API Reference：Scalar.Aws.Lambda 集成实战指南

在 AWS Lambda 上托管 Scalar API ReferenceScalar.Aws.Lambda 集成实战指南【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalarScalar.Aws.Lambda是 Scalar 官方 .NET 集成家族中的一员它让你可以在由Amazon API Gateway HTTP APIpayload format 2.0托管的 AWS Lambda 函数内部直接渲染出 Scalar API Reference 交互式文档。它同时提供零依赖注入zero-DI的静态工厂入口与标准 DI 注册入口并与Scalar.Azure.Functions共享同一套无服务器渲染内核。读完本文你将掌握从安装、双入口选型、API Gateway 路由声明到 Stage 前缀处理、OpenAPI 文档挂载与既有限制规避的完整落地路径。1. 从变更记录看这个集成的诞生在 integrations/dotnet/aws-lambda/CHANGELOG.md 中Scalar.Aws.Lambda的演进清晰可循0.1.0首次引入该集成用于渲染由 Amazon API Gateway HTTP APIpayload format 2.0前置的 AWS Lambda 函数中的 Scalar API Reference。0.2.0正式补充双入口支持——零 DI 静态工厂ScalarApiReferenceHandler.Create与 DI 注册服务AddScalarApiReference/IScalarApiReference。同版本内还完成了一项重要的架构调整原本支撑Scalar.Azure.Functions的托管无关请求处理器request processor、渲染结果render result与静态资源表static-asset table被下沉到共享工程并通过新的SCALAR_SERVERLESS编译常量复用Scalar.AspNetCore、Scalar.Aspire、Scalar.Azure.Functions均无公开 API 与行为变化。也就是说AWS Lambda 与 Azure Functions 两条无服务器集成线共享同一套渲染内核这正是Scalar.Aws.Lambda可以做到“行为与 Azure 集成镜像一致”的底层原因。源码层面该常量的生效位置在 Scalar.Aws.Lambda.csproj 的DefineConstantsSCALAR_AWS_LAMBDA;SCALAR_SERVERLESS共享代码则通过Compile Include../../../shared/src/Scalar.Shared/**/*.cs ...直接编译进本程序集。[!NOTE] 本集成仅支持 API Gateway HTTP API。REST APIpayload format 1.0、Application Load Balancer 与 Lambda Function URLs 不在当前支持范围内详见下文 第 8 节。2. 安装在 Lambda 函数工程中执行dotnet add package Scalar.Aws.Lambda从 Scalar.Aws.Lambda.csproj 可以看到该包的目标框架为net8.0;net9.0;net10.0依赖Amazon.Lambda.Core、Amazon.Lambda.APIGatewayEvents、Microsoft.Extensions.DependencyInjection.Abstractions与Microsoft.Extensions.Options。静态资源scalar.js、favicon.svg等以 EmbeddedResource 形式随包分发Release 构建下默认使用 gzip 压缩版本Debug 下使用未压缩版本无需额外部署静态文件。3. 两个入口零 DI 静态工厂与 DI 注册服务该包的两个入口共享同一套实现ScalarApiReference选择依据是你函数的托管方式。Option A — 零 DI 静态工厂适用于无依赖注入容器的普通 Lambda 函数。ScalarApiReferenceHandler.Create(...)返回一个可直接作为 Lambda 入口使用的FuncAPIGatewayHttpApiV2ProxyRequest, ILambdaContext, TaskAPIGatewayHttpApiV2ProxyResponse委托using Amazon.Lambda.APIGatewayEvents; using Amazon.Lambda.RuntimeSupport; using Amazon.Lambda.Serialization.SystemTextJson; using Scalar.Aws.Lambda; var handler ScalarApiReferenceHandler.Create(options { options.Title My API; }); await LambdaBootstrapBuilder.CreateAPIGatewayHttpApiV2ProxyRequest, APIGatewayHttpApiV2ProxyResponse(handler, new DefaultLambdaJsonSerializer()) .Build() .RunAsync();从源码看ScalarApiReferenceHandler.Create 内部构造了一个StaticOptionsSnapshot——一个实现IOptionsSnapshotScalarOptions的最小适配器它在每次访问时都构建全新的ScalarOptions实例从而模拟 DI 路径中IOptionsSnapshot的按请求生命周期保证两次调用之间不会串状态。Option B — 依赖注入适用于使用Amazon.Lambda.RuntimeSupport泛型宿主托管 Lambda 的场景using Microsoft.Extensions.DependencyInjection; using Scalar.Aws.Lambda; var services new ServiceCollection(); services.AddScalarApiReference(options { options.Title My API; }); await using var provider services.BuildServiceProvider(); // IScalarApiReference 注册为 Scoped请按 Lambda DI 的标准实践每次调用创建独立 scope。 using var scope provider.CreateScope(); var scalar scope.ServiceProvider.GetRequiredServiceIScalarApiReference(); var response await scalar.HandleAsync(request, context);AddScalarApiReference 的实现做了两件事始终注册IOptionsSnapshotScalarOptions基础设施即使未传入配置回调并将IScalarApiReference注册为Scoped服务。因此务必避免从根 provider 直接解析应遵循“每次调用新建 scope”的 Lambda 惯例。两个入口的等价性有测试保障ScalarApiReferenceHandlerTests.cs 中的Create_And_Di_ShouldProduceIdenticalResponses_ForSameInput对同一输入分别走两个入口断言StatusCode、Body、IsBase64Encoded完全一致。4. 声明 API Gateway 路由{proxy}贪婪参数Scalar 需要接管某一路径下的所有请求因此必须使用{proxy}贪婪路径参数类似 ASP.NET Core 的 catch-all 路由并为裸索引路径单独声明一条路由。以 SAM 模板为例Events: ScalarIndex: Type: HttpApi Properties: Path: /scalar Method: GET ScalarProxy: Type: HttpApi Properties: Path: /scalar/{proxy} Method: ANY仓库自带的 playground/template.yaml 给出了完整可运行的模板含Timeout: 10、MemorySize: 256、dotnet10运行时等 Globals 配置并导出ScalarApiUrl输出便于直接访问验证。路由语义根据 docs/http-api-model.md 中描述的{proxy}模型请求含义GET /scalar、GET /scalar/渲染默认文档的参考索引页GET /scalar/v3渲染v3文档的参考索引页GET /scalar/scalar.js、GET /scalar/scalar.aws.lambda.js、GET /scalar/favicon.svg提供内嵌的静态资源实现上ScalarApiReference.HandleAsync 直接从request.PathParameters[proxy]读取路径余量RouteRemainderKey proxy交由共享的ScalarRequestProcessor.Process(...)位于 integrations/dotnet/shared/src/Scalar.Shared/Rendering/ScalarRequestProcessor.cs解析文档名与静态资源。[!NOTE] 若PathParameters完全不存在例如函数被直接调用而未经过 API Gateway 代理集成请求会被当作索引请求处理而不是抛异常这也被测试覆盖。5. 指向 OpenAPI 文档默认情况下Scalar 会在相对参考页的openapi/{documentName}.json路径查找 OpenAPI 文档。也就是说你需要把你的文档暴露在openapi/v1.json默认文档名v1这个路由上或者改变模式options.AddDocument(v1, routePattern: openapi/v1.json);测试 ScalarApiReferenceHandlerTests.cs 验证了默认行为请求/scalar/时响应体中包含openapi/v1.json而请求/scalar/v3后再请求/scalar/响应中不会再出现openapi/v3.json——Create_ShouldNotLeakDocumentState_AcrossInvocations这个回归测试专门保证了静态工厂每次调用都拿到全新的ScalarOptions避免前一次请求设置的文档状态泄漏到下一次调用。6. Stage 与路由前缀自动检测与手动覆盖API Gateway HTTP API 会把命名 stage 作为路径段嵌入RawPath但特殊的$defaultstage 不会。Scalar.Aws.Lambda的行为如下StageGET /scalar/的RawPath行为$default/scalar/不剥离任何前缀prod/prod/scalar/自动检测prod并从相对 URL 中剥离实现位于 ScalarApiReference.ApplyRoutePrefix当ScalarOptions.RoutePrefix尚未被显式设置时读取request.RequestContext.Stage若为非空且不等于$default则把 stage 名折入RoutePrefix。这与 ScalarOptions.AwsLambda.cs 中RoutePrefix的文档描述一致——它镜像了 Azure Functions 集成把host.json的routePrefix折入同一选项的做法。对应测试Create_ShouldAutoDetectStage_LikeDiEntryPointScalarApiReferenceHandlerTests.cs验证了在prodstage 下渲染出的 HTML 引用/scalar/而非/prod/scalar/。特殊情况如果你使用自定义域名custom domain的 base path mapping该前缀不会反映在RequestContext.Stage中此时必须显式设置options.RoutePrefix my-base-path;7. HTTP 事件模型与响应细节请求头处理HTTP API 会把 header 名转为小写并在headers字段中用逗号合并重复头没有 payload format 1.0 那样的multiValueHeaders。Scalar.Aws.Lambda读取Accept-Encoding与If-None-Match时大小写不敏感见 ScalarApiReference.GetHeader因此无论 API Gateway 小写化还是直接测试调用时的大写形式都能正确处理。响应体编码APIGatewayHttpApiV2ProxyResponse.IsBase64Encoded仅在响应体为 gzip 压缩的二进制静态资源时为trueHTML 页面与未压缩静态资源以普通 UTF-8 文本返回IsBase64Encoded false。BuildResponseAsync 完整地实现了状态码协商302RedirectLocation非空时附带Location头304NotModified为真时携带ETag、Cache-Control必要时追加Vary: Accept-Encoding404渲染结果 404 时直接返回200填充Cache-Control、Vary、ETag、Content-Type二进制 gzip 资源 base64 编码并标记IsBase64Encoded true。按请求定制配置两个入口都支持可选的每请求配置回调// 静态工厂 var handler ScalarApiReferenceHandler.Create(options options.Title My API); // DI 路径HandleAsync 的第三个参数可拿到原始请求 var response await scalar.HandleAsync(request, context, (options, req) { options.Title $My API ({req.RequestContext.DomainName}); });IScalarApiReference.HandleAsync的完整签名IScalarApiReference.cs支持ActionScalarOptions, APIGatewayHttpApiV2ProxyRequest? configureOptions让你可以根据请求上下文如 DomainName动态调整标题、文档等配置。8. 限制与路线图参考 docs/limitations.md当前版本有以下边界需要知晓必须自行提供函数与 Azure Functions 集成一致不同于 ASP.NET Core 集成中MapScalarApiReference()自动注册端点你需要自己声明 Lambda 函数并把请求转发给IScalarApiReference或ScalarApiReferenceHandler.Create(...)返回的委托。仅支持 API Gateway HTTP APIpayload format 2.0以下事件源暂不支持API Gateway REST APIpayload format 1.0——APIGatewayProxyRequest/APIGatewayProxyResponseApplication Load Balancer 目标组Lambda Function URLs。官方给出的原因是这些事件形状在路由/路径参数解析、请求头结构、stage 处理上差异过大值得做专门的适配器而非尽力而为的 shim。这也是 roadmap 项若当下就需要可以自行调用Scalar.Shared中的底层构建块等价于ScalarRequestProcessor的逻辑或改用Scalar.AspNetCore配合Amazon.Lambda.AspNetCoreServer在 Lambda 中托管完整 ASP.NET Core 应用。catch-all 参数名固定为proxy例如Path: /scalar/{proxy}适配器从request.PathParameters[proxy]读取该值来区分静态资源请求与参考页、解析文档名。自定义域名 base pathstage 自动检测读不到 base path mapping请显式设置ScalarOptions.RoutePrefix。完整 ASP.NET Core 应用若通过Amazon.Lambda.AspNetCoreServer/Amazon.Lambda.AspNetCoreServer.Hosting托管完整应用直接使用Scalar.AspNetCore包的MapScalarApiReference()即可无需本包。9. 源码结构速览想要进一步深入可以从以下文件入手integrations/dotnet/aws-lambda/docs/getting-started.md完整的安装、双入口、路由声明与配置指南integrations/dotnet/aws-lambda/docs/http-api-model.mdHTTP API 事件模型、stage 处理与 header/编码细节integrations/dotnet/aws-lambda/docs/limitations.md限制与 roadmapintegrations/dotnet/aws-lambda/src/Scalar.Aws.Lambda/ScalarApiReference.cs核心请求处理、stage 折叠与响应构建integrations/dotnet/aws-lambda/src/Scalar.Aws.Lambda/ScalarApiReferenceHandler.cs零 DI 入口及按访问构建选项的适配器integrations/dotnet/aws-lambda/tests/Scalar.Aws.Lambda.Tests/ScalarApiReferenceHandlerTests.cs覆盖索引渲染、stage 自动检测、状态隔离与双入口一致性的测试integrations/dotnet/shared/src/Scalar.Shared/Rendering/ScalarRequestProcessor.cs与 Azure Functions 共享的托管无关请求处理器integrations/dotnet/aws-lambda/playground/template.yaml可直接部署验证的 SAM 模板。总而言之Scalar.Aws.Lambda让 .NET 开发者可以在不改动现有 Lambda 业务函数架构的前提下以最少代码甚至零 DI挂载一套完整的、支持 stage 自动适配与 gzip 静态资源的 Scalar API Reference 页面。只要遵循{proxy}路由、payload format 2.0 与proxy参数名的约定即可在几分钟内完成 API 文档的云上托管。【免费下载链接】scalarScalar is an open-source API platform: Modern REST API Client Beautiful API References ✨ 1st-Class OpenAPI/Swagger Support项目地址: https://gitcode.com/GitHub_Trending/sc/scalar创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考