跳到正文

Fast.OpenApi ​

逐成员 API、参数与返回参考

本页接入示例使用 NuGet 上的 3.5.47,目标为 net8.0、net9.0、net10.0。模块从 Swagger JSON 与当前应用的 API 描述生成 JavaScript/TypeScript 客户端资源。

参考源码版本 3.5.47。

bash
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() 表示正常宿主启动;启动后,客户端生成需按下文显式触发。

csharp
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();
字段默认与作用
FolderGrouptrue,客户端 services 按文档分组建立子目录
ImportSchemaMappings默认映射 ElSelectorOutput、ElTreeOutput、FaTableEnumColumnCtx、PagedInput、PagedResult;Web 入口为 fast-element-plus
ImportTypeMappings处理响应包装、分页、集合与字典等类型名称映射
IgnoreSchemas空集合
PagedSchemaProperties默认包含 pageIndex、pageSize、searchValue、searchTimeList、searchList、sortList、enablePaged、isOrderBy
BaseTypeMappingsInt64/int64/long 映射为 string,Int32 为 number,Object 为 unknown,binary 为 Blob 等

OpenApiImportSchemaMappingSettingsOptions 包含 Name、MappingName、WebImportPath、MobileImportPath;MappingName 空时使用 Name。OpenApiImportTypeMappingSettingsOptions 包含 Name、MappingName、RefSchema,MappingName 的 {0} 用于组合匹配后的类型。字段不为 null 时不会自动合并整套默认映射,替换集合需保留消费方需要的项。

生成 API 与副作用 ​

csharp
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 端点,也不要加入普通文档构建或应用启动流程。

csharp
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 有效包元数据,按要求不运行测试,也未执行还原、构建、打包或消费端运行验证。