Scalar.Aws.Lambda 集成指南在 AWS Lambda 中渲染 Scalar API Reference【免费下载链接】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 是一个开源的 API 平台提供了美观的 API References 与一流的 OpenAPI/Swagger 支持。Scalar.Aws.Lambda是 Scalar 官方为 AWS 生态提供的 .NET 集成包让你可以直接在由 Amazon API Gateway HTTP API 前置的 AWS Lambda 函数中基于 OpenAPI/Swagger 文档渲染出交互式的 API 参考页面。读完本文你将掌握Scalar.Aws.Lambda的两种接入方式零 DI 静态工厂与依赖注入、{proxy}路由声明、Stage 前缀自动识别、静态资源与文档的解析规则以及当前版本的支持边界与已知限制。包定位与适用场景Scalar.Aws.LambdaNuGet 包名Scalar.Aws.Lambda提供的核心能力是在 AWS Lambda 函数中直接渲染 Scalar API Reference而无需单独托管一个 Web 服务。它面向的典型架构是浏览器 ──▶ Amazon API Gateway HTTP API ──▶ AWS Lambda (Scalar.Aws.Lambda) ──▶ OpenAPI 文档从 CHANGELOG.md 可以看到该集成在 0.2.0 版本中随#9764引入同时提供了两条等价的接入路径零 DI 的静态 handler 工厂ScalarApiReferenceHandler.Create和DI 注册服务AddScalarApiReference/IScalarApiReference。值得注意的是驱动它的请求处理器、渲染结果与静态资源表是从共享项目中迁移而来的并受到SCALAR_SERVERLESS常量保护因此Scalar.AspNetCore、Scalar.Aspire、Scalar.Azure.Functions均未受任何行为影响——这也意味着你可以在 Azure Functions 与 AWS Lambda 之间复用同一套 serverless 渲染逻辑。[!NOTE] 当前版本仅支持API Gateway HTTP APIpayload format 2.0。REST APIpayload format 1.0、Application Load Balancer 与 Lambda Function URL 均不在首批支持范围内详见下文限制与路线图。快速开始安装与接入1. 安装包dotnet add package Scalar.Aws.Lambda2. 选择入口Scalar.Aws.Lambda提供两个共享同一套实现的入口按你函数的托管方式任选其一即可。方案 A —— 零 DI 静态工厂适用于没有依赖注入容器的普通 Lambda 函数。ScalarApiReferenceHandler.Create(...)会返回一个可直接作为 Lambda 入口使用的请求/响应委托ScalarApiReferenceHandler.csusing 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();从源码结构看Create内部维护了一个极简的StaticOptionsSnapshot它实现了IOptionsSnapshotScalarOptions在每次访问时都构建一份全新的ScalarOptions并应用配置回调从而在无 DI 场景下模拟出 DI 路径中IOptionsSnapshot的按请求生命周期让ScalarApiReference成为两个入口共享的唯一传输逻辑实现ScalarApiReferenceHandler.cs。方案 B —— 依赖注入适用于使用Amazon.Lambda.RuntimeSupport泛型主机托管的 Lambda 函数。注册 Scalar 服务后解析IScalarApiReference即可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 方式注册请按每次调用创建独立 DI 作用域 using var scope provider.CreateScope(); var scalar scope.ServiceProvider.GetRequiredServiceIScalarApiReference(); var response await scalar.HandleAsync(request, context);[!IMPORTANT]IScalarApiReference以Scoped生命周期注册见 ScalarServiceCollectionExtensions.cs。请遵循标准的 Lambda DI 规范在每次调用时新建 DI 作用域而不要从根 provider 直接解析。3. 声明 API Gateway 路由路由必须使用{proxy}贪婪路径参数并为裸索引路径额外声明一条普通路由。以 SAM 模板为例Events: ScalarIndex: Type: HttpApi Properties: Path: /scalar Method: GET ScalarProxy: Type: HttpApi Properties: Path: /scalar/{proxy} Method: ANY仓库自带的 playground/template.yaml 即采用这一模式并额外给出可直接上手的完整骨架Runtime: dotnet10、Handler: Scalar.Aws.Lambda.Playground、函数级Timeout: 10/MemorySize: 256输出ScalarApiUrl指向https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com/scalar/可作为你部署时的最小参考。4. 指向你的 OpenAPI 文档默认情况下Scalar 会从openapi/{documentName}.json相对于 reference 的路径查找 OpenAPI 文档。你可以在该路由暴露文档也可以改变匹配模式options.AddDocument(v1, routePattern: openapi/v1.json);5. Stage 与路由前缀当你的 API Gateway stage不是$default例如prod时Scalar.Aws.Lambda会自动探测 stage 名并将其从渲染出的相对 URL 中剥离无需额外配置。若你使用了自定义域名 base path mapping该前缀对 stage 名不可见则需要显式设置ScalarOptions.RoutePrefixoptions.RoutePrefix my-base-path;RoutePrefix定义在 ScalarOptions.AwsLambda.cs当其值为null默认时前缀会从request.RequestContext.Stage自动探测HTTP API 在$defaultstage 下不会把 stage 嵌入路径因此该场景不加任何前缀。按请求定制配置两个入口都接受一个可选回调用于按请求定制选项// 静态工厂 var handler ScalarApiReferenceHandler.Create(options options.Title My API); // DI var response await scalar.HandleAsync(request, context, (options, req) { options.Title $My API ({req.RequestContext.DomainName}); });深入理解 HTTP API 事件模型payload format 2.0Scalar.Aws.Lambda只支持HTTP API payload format 2.0即Amazon.Lambda.APIGatewayEvents中的APIGatewayHttpApiV2ProxyRequest/APIGatewayHttpApiV2ProxyResponse。理解这一事件模型的细节是正确配置路由与排查问题的关键。{proxy}路由的解析HTTP API 支持贪婪路径参数{proxy}其语义类似 ASP.NET Core 的 catch-all 路由参数。声明{proxy}后Scalar 会直接从request.PathParameters[proxy]读取路径剩余部分见 ScalarApiReference.cs常量RouteRemainderKey proxyGET /scalar与GET /scalar/渲染默认文档的 reference 索引页。GET /scalar/v3渲染v3文档的 reference 索引页。GET /scalar/scalar.js、GET /scalar/scalar.aws.lambda.js、GET /scalar/favicon.svg提供内嵌的静态资源。另外如果PathParameters完全不存在例如函数被直接调用、未经过 API Gateway 代理集成请求会被当作索引请求处理而不是抛错这为本地调试提供了便利。Stage 处理HTTP API 对任何命名 stage都会把 stage 名作为路径段嵌入RawPath唯独特殊的$defaultstage 不会StageGET /scalar/对应的RawPath行为$default/scalar/不剥离前缀。prod/prod/scalar/自动探测并剥离prod避免其泄漏到相对 URL。实现上HandleAsync在每次请求时先调用ApplyRoutePrefix只有RoutePrefix尚未被显式设置时才会读取request.RequestContext.Stage并将命名 stage 折叠进RoutePrefixScalarApiReference.cs。这与 Azure Functions 集成将host.json的routePrefix折叠进同一选项的做法相互呼应。而自定义域名 base path mapping 添加的前缀不会反映在RequestContext.Stage中——此时必须显式设置ScalarOptions.RoutePrefix为该 base path。Header 处理API Gateway HTTP API 会把 header 名转为小写并在headers字段中用逗号合并重复 header与 REST API / payload format 1.0 不同这里没有multiValueHeaders字段。Scalar.Aws.Lambda以大小写不敏感方式读取Accept-Encoding与If-None-Match见 ScalarApiReference.cs 的AcceptsGzip/GetHeader因此无论调用方如何书写 header 大小写API Gateway 通常已小写化但直接测试调用可能不会都能正确处理。响应体编码APIGatewayHttpApiV2ProxyResponse.IsBase64Encoded仅在响应体为gzip 压缩的静态资源二进制内容时为trueHTML 页面与未压缩的静态资源则以纯 UTF-8 文本返回IsBase64Encoded false。BuildResponseAsync的实现ScalarApiReference.cs完整覆盖了四种响应形态302设置Location头用于重定向如GET /scalar→/scalar/。304携带ETag/Cache-Control必要时加Vary: Accept-Encoding配合If-None-Match实现条件请求。404资源不存在时直接返回。200携带Cache-Control、Vary、ETag、Content-Type正文为 HTML 或base64 编码的二进制静态资源。限制与路线图你必须自己提供函数与 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/APIGatewayProxyResponse。Application Load Balancer目标组。Lambda Function URL。这些事件形状在路由/路径参数解析、header 结构、stage 处理上差异足够大值得为它们编写专门的适配器而非勉强做兼容 shim——这已列入路线图。如果你现在就需要其中一种可以通过Scalar.Shared中的底层构件自行实现等价的ScalarRequestProcessor逻辑如果你是在 Lambda 中托管完整的 ASP.NET Core 应用通过Amazon.Lambda.AspNetCoreServer则应直接使用Scalar.AspNetCore包的MapScalarApiReference()。路由参数名必须为proxycatch-all 路由参数必须命名为proxy例如Path: /scalar/{proxy}。适配器通过request.PathParameters[proxy]区分静态资源请求与 reference 页面并解析文档名。自定义域名 base path mappingStage 自动探测读取的是request.RequestContext.Stage它不会反映自定义域名的 base path mapping。若你使用自定义域名请将ScalarOptions.RoutePrefix显式设置为该 base path。源码结构速览如果你希望深入阅读实现或参与贡献本集成在仓库中的组织方式如下入口与接口ScalarApiReferenceHandler.cs零 DI 静态工厂、IScalarApiReference.csDI 服务接口、ScalarApiReference.cs核心请求处理与响应构建。扩展与选项ScalarServiceCollectionExtensions.csAddScalarApiReference注册、ScalarOptions.AwsLambda.csRoutePrefix选项。内嵌静态资源StaticAssets目录下的scalar.aws.lambda.js与favicon.svg。可运行样例playground/template.yaml 与playground/Function.csSAM 本地 playground。测试tests/Scalar.Aws.Lambda.Tests下的ScalarApiReferenceHandlerTests.cs、ScalarApiReferenceTests.cs、ScalarRequestProcessorTests.cs覆盖了入口、stage 前缀与请求处理的核心行为是理解预期行为的良好参考。综上Scalar.Aws.Lambda以极低的接入成本让 serverless 架构获得完整的 Scalar API Reference 渲染能力两条等价入口覆盖有无 DI 容器的两种托管方式{proxy} stage 自动识别让路由声明几乎零配置而条件请求、gzip 静态资源与明确的错误响应则保证了生产环境下的行为可预期。结合本文的源码级说明与 getting-started.md、http-api-model.md、limitations.md 等文档你可以快速完成从包安装到 SAM 部署的完整链路。【免费下载链接】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），仅供参考 Scalar.Aws.Lambda 集成指南：在 AWS Lambda 中渲染 Scalar API Reference
Scalar.Aws.Lambda 集成指南在 AWS Lambda 中渲染 Scalar API Reference【免费下载链接】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 是一个开源的 API 平台提供了美观的 API References 与一流的 OpenAPI/Swagger 支持。Scalar.Aws.Lambda是 Scalar 官方为 AWS 生态提供的 .NET 集成包让你可以直接在由 Amazon API Gateway HTTP API 前置的 AWS Lambda 函数中基于 OpenAPI/Swagger 文档渲染出交互式的 API 参考页面。读完本文你将掌握Scalar.Aws.Lambda的两种接入方式零 DI 静态工厂与依赖注入、{proxy}路由声明、Stage 前缀自动识别、静态资源与文档的解析规则以及当前版本的支持边界与已知限制。包定位与适用场景Scalar.Aws.LambdaNuGet 包名Scalar.Aws.Lambda提供的核心能力是在 AWS Lambda 函数中直接渲染 Scalar API Reference而无需单独托管一个 Web 服务。它面向的典型架构是浏览器 ──▶ Amazon API Gateway HTTP API ──▶ AWS Lambda (Scalar.Aws.Lambda) ──▶ OpenAPI 文档从 CHANGELOG.md 可以看到该集成在 0.2.0 版本中随#9764引入同时提供了两条等价的接入路径零 DI 的静态 handler 工厂ScalarApiReferenceHandler.Create和DI 注册服务AddScalarApiReference/IScalarApiReference。值得注意的是驱动它的请求处理器、渲染结果与静态资源表是从共享项目中迁移而来的并受到SCALAR_SERVERLESS常量保护因此Scalar.AspNetCore、Scalar.Aspire、Scalar.Azure.Functions均未受任何行为影响——这也意味着你可以在 Azure Functions 与 AWS Lambda 之间复用同一套 serverless 渲染逻辑。[!NOTE] 当前版本仅支持API Gateway HTTP APIpayload format 2.0。REST APIpayload format 1.0、Application Load Balancer 与 Lambda Function URL 均不在首批支持范围内详见下文限制与路线图。快速开始安装与接入1. 安装包dotnet add package Scalar.Aws.Lambda2. 选择入口Scalar.Aws.Lambda提供两个共享同一套实现的入口按你函数的托管方式任选其一即可。方案 A —— 零 DI 静态工厂适用于没有依赖注入容器的普通 Lambda 函数。ScalarApiReferenceHandler.Create(...)会返回一个可直接作为 Lambda 入口使用的请求/响应委托ScalarApiReferenceHandler.csusing 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();从源码结构看Create内部维护了一个极简的StaticOptionsSnapshot它实现了IOptionsSnapshotScalarOptions在每次访问时都构建一份全新的ScalarOptions并应用配置回调从而在无 DI 场景下模拟出 DI 路径中IOptionsSnapshot的按请求生命周期让ScalarApiReference成为两个入口共享的唯一传输逻辑实现ScalarApiReferenceHandler.cs。方案 B —— 依赖注入适用于使用Amazon.Lambda.RuntimeSupport泛型主机托管的 Lambda 函数。注册 Scalar 服务后解析IScalarApiReference即可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 方式注册请按每次调用创建独立 DI 作用域 using var scope provider.CreateScope(); var scalar scope.ServiceProvider.GetRequiredServiceIScalarApiReference(); var response await scalar.HandleAsync(request, context);[!IMPORTANT]IScalarApiReference以Scoped生命周期注册见 ScalarServiceCollectionExtensions.cs。请遵循标准的 Lambda DI 规范在每次调用时新建 DI 作用域而不要从根 provider 直接解析。3. 声明 API Gateway 路由路由必须使用{proxy}贪婪路径参数并为裸索引路径额外声明一条普通路由。以 SAM 模板为例Events: ScalarIndex: Type: HttpApi Properties: Path: /scalar Method: GET ScalarProxy: Type: HttpApi Properties: Path: /scalar/{proxy} Method: ANY仓库自带的 playground/template.yaml 即采用这一模式并额外给出可直接上手的完整骨架Runtime: dotnet10、Handler: Scalar.Aws.Lambda.Playground、函数级Timeout: 10/MemorySize: 256输出ScalarApiUrl指向https://${ServerlessHttpApi}.execute-api.${AWS::Region}.amazonaws.com/scalar/可作为你部署时的最小参考。4. 指向你的 OpenAPI 文档默认情况下Scalar 会从openapi/{documentName}.json相对于 reference 的路径查找 OpenAPI 文档。你可以在该路由暴露文档也可以改变匹配模式options.AddDocument(v1, routePattern: openapi/v1.json);5. Stage 与路由前缀当你的 API Gateway stage不是$default例如prod时Scalar.Aws.Lambda会自动探测 stage 名并将其从渲染出的相对 URL 中剥离无需额外配置。若你使用了自定义域名 base path mapping该前缀对 stage 名不可见则需要显式设置ScalarOptions.RoutePrefixoptions.RoutePrefix my-base-path;RoutePrefix定义在 ScalarOptions.AwsLambda.cs当其值为null默认时前缀会从request.RequestContext.Stage自动探测HTTP API 在$defaultstage 下不会把 stage 嵌入路径因此该场景不加任何前缀。按请求定制配置两个入口都接受一个可选回调用于按请求定制选项// 静态工厂 var handler ScalarApiReferenceHandler.Create(options options.Title My API); // DI var response await scalar.HandleAsync(request, context, (options, req) { options.Title $My API ({req.RequestContext.DomainName}); });深入理解 HTTP API 事件模型payload format 2.0Scalar.Aws.Lambda只支持HTTP API payload format 2.0即Amazon.Lambda.APIGatewayEvents中的APIGatewayHttpApiV2ProxyRequest/APIGatewayHttpApiV2ProxyResponse。理解这一事件模型的细节是正确配置路由与排查问题的关键。{proxy}路由的解析HTTP API 支持贪婪路径参数{proxy}其语义类似 ASP.NET Core 的 catch-all 路由参数。声明{proxy}后Scalar 会直接从request.PathParameters[proxy]读取路径剩余部分见 ScalarApiReference.cs常量RouteRemainderKey proxyGET /scalar与GET /scalar/渲染默认文档的 reference 索引页。GET /scalar/v3渲染v3文档的 reference 索引页。GET /scalar/scalar.js、GET /scalar/scalar.aws.lambda.js、GET /scalar/favicon.svg提供内嵌的静态资源。另外如果PathParameters完全不存在例如函数被直接调用、未经过 API Gateway 代理集成请求会被当作索引请求处理而不是抛错这为本地调试提供了便利。Stage 处理HTTP API 对任何命名 stage都会把 stage 名作为路径段嵌入RawPath唯独特殊的$defaultstage 不会StageGET /scalar/对应的RawPath行为$default/scalar/不剥离前缀。prod/prod/scalar/自动探测并剥离prod避免其泄漏到相对 URL。实现上HandleAsync在每次请求时先调用ApplyRoutePrefix只有RoutePrefix尚未被显式设置时才会读取request.RequestContext.Stage并将命名 stage 折叠进RoutePrefixScalarApiReference.cs。这与 Azure Functions 集成将host.json的routePrefix折叠进同一选项的做法相互呼应。而自定义域名 base path mapping 添加的前缀不会反映在RequestContext.Stage中——此时必须显式设置ScalarOptions.RoutePrefix为该 base path。Header 处理API Gateway HTTP API 会把 header 名转为小写并在headers字段中用逗号合并重复 header与 REST API / payload format 1.0 不同这里没有multiValueHeaders字段。Scalar.Aws.Lambda以大小写不敏感方式读取Accept-Encoding与If-None-Match见 ScalarApiReference.cs 的AcceptsGzip/GetHeader因此无论调用方如何书写 header 大小写API Gateway 通常已小写化但直接测试调用可能不会都能正确处理。响应体编码APIGatewayHttpApiV2ProxyResponse.IsBase64Encoded仅在响应体为gzip 压缩的静态资源二进制内容时为trueHTML 页面与未压缩的静态资源则以纯 UTF-8 文本返回IsBase64Encoded false。BuildResponseAsync的实现ScalarApiReference.cs完整覆盖了四种响应形态302设置Location头用于重定向如GET /scalar→/scalar/。304携带ETag/Cache-Control必要时加Vary: Accept-Encoding配合If-None-Match实现条件请求。404资源不存在时直接返回。200携带Cache-Control、Vary、ETag、Content-Type正文为 HTML 或base64 编码的二进制静态资源。限制与路线图你必须自己提供函数与 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/APIGatewayProxyResponse。Application Load Balancer目标组。Lambda Function URL。这些事件形状在路由/路径参数解析、header 结构、stage 处理上差异足够大值得为它们编写专门的适配器而非勉强做兼容 shim——这已列入路线图。如果你现在就需要其中一种可以通过Scalar.Shared中的底层构件自行实现等价的ScalarRequestProcessor逻辑如果你是在 Lambda 中托管完整的 ASP.NET Core 应用通过Amazon.Lambda.AspNetCoreServer则应直接使用Scalar.AspNetCore包的MapScalarApiReference()。路由参数名必须为proxycatch-all 路由参数必须命名为proxy例如Path: /scalar/{proxy}。适配器通过request.PathParameters[proxy]区分静态资源请求与 reference 页面并解析文档名。自定义域名 base path mappingStage 自动探测读取的是request.RequestContext.Stage它不会反映自定义域名的 base path mapping。若你使用自定义域名请将ScalarOptions.RoutePrefix显式设置为该 base path。源码结构速览如果你希望深入阅读实现或参与贡献本集成在仓库中的组织方式如下入口与接口ScalarApiReferenceHandler.cs零 DI 静态工厂、IScalarApiReference.csDI 服务接口、ScalarApiReference.cs核心请求处理与响应构建。扩展与选项ScalarServiceCollectionExtensions.csAddScalarApiReference注册、ScalarOptions.AwsLambda.csRoutePrefix选项。内嵌静态资源StaticAssets目录下的scalar.aws.lambda.js与favicon.svg。可运行样例playground/template.yaml 与playground/Function.csSAM 本地 playground。测试tests/Scalar.Aws.Lambda.Tests下的ScalarApiReferenceHandlerTests.cs、ScalarApiReferenceTests.cs、ScalarRequestProcessorTests.cs覆盖了入口、stage 前缀与请求处理的核心行为是理解预期行为的良好参考。综上Scalar.Aws.Lambda以极低的接入成本让 serverless 架构获得完整的 Scalar API Reference 渲染能力两条等价入口覆盖有无 DI 容器的两种托管方式{proxy} stage 自动识别让路由声明几乎零配置而条件请求、gzip 静态资源与明确的错误响应则保证了生产环境下的行为可预期。结合本文的源码级说明与 getting-started.md、http-api-model.md、limitations.md 等文档你可以快速完成从包安装到 SAM 部署的完整链路。【免费下载链接】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），仅供参考