Fast.OpenApi
本页接入示例使用 NuGet 上的 3.5.47,目标为 net8.0、net9.0、net10.0。模块从 Swagger JSON 与当前应用的 API 描述生成 JavaScript/TypeScript 客户端资源。
参考源码版本 3.5.47。
dotnet add package Fast.OpenApi --version 3.5.47注册入口与选项
AddOpenApi(this IServiceCollection services, IConfiguration configuration, string section = "OpenApiSettings") 返回服务集合,绑定并后配置 OpenApiSettingsOptions。注意实际默认节点是 OpenApiSettings。
以下为消费端 Program.cs,使用 Microsoft.NET.Sdk.Web,目标选择本页列出的 .NET 8、9 或 10,并安装上方指定包。app.Run() 表示正常宿主启动;启动后,客户端生成需按下文显式触发。
using Fast.OpenApi;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddOpenApi(builder.Configuration, "OpenApiSettings");
var app = builder.Build();
app.MapControllers();
app.Run();| 字段 | 默认与作用 |
|---|---|
FolderGroup | true,客户端 services 按文档分组建立子目录 |
ImportSchemaMappings | 默认映射 ElSelectorOutput、ElTreeOutput、FaTableEnumColumnCtx、PagedInput、PagedResult;Web 入口为 fast-element-plus |
ImportTypeMappings | 处理响应包装、分页、集合与字典等类型名称映射 |
IgnoreSchemas | 空集合 |
PagedSchemaProperties | 默认包含 pageIndex、pageSize、searchValue、searchTimeList、searchList、sortList、enablePaged、isOrderBy |
BaseTypeMappings | Int64/int64/long 映射为 string,Int32 为 number,Object 为 unknown,binary 为 Blob 等 |
OpenApiImportSchemaMappingSettingsOptions 包含 Name、MappingName、WebImportPath、MobileImportPath;MappingName 空时使用 Name。OpenApiImportTypeMappingSettingsOptions 包含 Name、MappingName、RefSchema,MappingName 的 {0} 用于组合匹配后的类型。字段不为 null 时不会自动合并整套默认映射,替换集合需保留消费方需要的项。
生成 API 与副作用
public static Task GenerateOpenApi(
string address,
IApiDescriptionGroupCollectionProvider apiDescriptionGroupCollectionProvider,
List<string> groupList = null);该方法位于 OpenApiUtil,返回 Task,无输出目录参数。address 为空或不是绝对地址时抛 ArgumentException,描述提供器为空抛 ArgumentNullException。
调用会请求 {address}/swagger/{group}/swagger.json,在应用基目录下使用 Fast.OpenApi 输出目录;已存在时递归删除该输出目录后重新生成。默认分组为 All Groups,并补充 Default;会复制传入列表,不直接修改调用者集合。不要将地址查询、文件生成或此方法的调用放入只读文档检查。
每组生成 Web/Mobile、JavaScript/TypeScript 四种组合,包含 enums、services、声明等资源。生成成功不代表目标前端工程已编译或接口已经运行。
生成协议与公开 DTO
- TypeScript 使用独立
import type、显式Promise<T>;非泛型 Task/ValueTask 返回Promise<void>。 - 文件下载保留 AxiosResponse:Web 为 Blob,Mobile 为 Blob/ArrayBuffer/string;
autoDownloadFile默认 true。上传可暴露onUploadProgress。 - 未确定 Schema 的值保持 unknown,不通过 any 伪造已知类型;Int64 的 string 映射需与服务端 JSON 协议一致。
OpenApiDocumentDto及 Info、Component、ComponentSchema、Tag、Path、PathMethod、Parameter、RequestBody、Response、Content、SchemaProperty 等 DTO 表示解析模型,并不承诺覆盖所有 OpenAPI 扩展。ScriptLanguageEnum区分 JavaScript 与 TypeScript;生成工具不是运行时 API 请求客户端。
显式触发客户端生成
下面的消费端服务使用上方已注册的 API Explorer。它应由受控的维护命令调用,不应暴露为匿名 HTTP 端点,也不要加入普通文档构建或应用启动流程。
using Fast.OpenApi;
using Microsoft.AspNetCore.Mvc.ApiExplorer;
public sealed class ClientExporter(IApiDescriptionGroupCollectionProvider descriptions)
{
public Task ExportAsync(Uri documentationHost, List<string> groups)
{
ArgumentNullException.ThrowIfNull(documentationHost);
if (!documentationHost.IsAbsoluteUri)
throw new ArgumentException("需要绝对地址", nameof(documentationHost));
return OpenApiUtil.GenerateOpenApi(documentationHost.AbsoluteUri, descriptions, groups);
}
}调用方须先核对输出目录与目标地址,确认允许清理原生成目录,再显式调用并等待返回任务。方法没有 CancellationToken 参数,也不返回生成文件列表。网络请求、解析和文件权限异常会使任务失败;本例仅展示调用合同,本次不会实际执行生成。
3.5.47 分页识别变更
从 3.5.47 起,默认 PagedSchemaProperties 包含 isOrderBy。Schema 包含集合中的全部字段时,生成的 TypeScript DTO 才会继承 PagedInput。生成器按名称省略集合中的字段,无论 Schema 是否满足分页识别条件。旧 Schema 缺少 isOrderBy 时,可显式配置与实际字段匹配的 PagedSchemaProperties,以保留分页继承。
已发布的 fast-element-plus@2.0.27 的 PagedInput 尚无 isOrderBy。如果 Schema 有该字段,且前端需要对它进行类型检查,可从自定义的 PagedSchemaProperties 中移除 isOrderBy,让生成器把它保留在 DTO 中。其余分页字段仍须匹配,生成的 DTO 才会继承 PagedInput。
来源与验证
依据 生成实现、配置。本轮未请求服务、删除目录或生成客户端,新增片段未编译。
2026-11-02 依赖链变更
2026-11-02 依赖链同步:该批次将本包从 3.5.45 递增至 3.5.46,依赖更新为 Fast.Runtime 3.5.37。Runtime 新增移动端 H5,并将 Android 及后续位依次后移;数字协议和掩码须迁移,消费端须重新编译并同步前端枚举,见 Runtime H5 迁移说明。下文历史批次保留当时的版本与验证范围。
2026-10-24 版本与依赖
2026-10-24 将本包从 3.5.42 递增至 3.5.43,依赖更新至 Fast.Runtime 3.5.34。本模块自身实现和公开声明未改。
使用 AppEnvironmentEnum 的消费端需按 Runtime 鸿蒙迁移说明迁移数值并重新编译。本轮只核对源码与 MSBuild 有效包元数据,按要求不运行测试,也未执行还原、构建、打包或消费端运行验证。
