Fast.OpenApi

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

版本 3.5.39；目标 net8.0、net9.0、net10.0；依赖 Fast.Runtime。从 Swagger JSON 与当前应用的 API 描述生成 JavaScript/TypeScript 客户端资源，不是 Swagger UI 服务本身。

dotnet add package Fast.OpenApi

注册入口与选项

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
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 参数，也不返回生成文件列表。网络请求、解析和文件权限异常会使任务失败；本例仅展示调用合同，本次不会实际执行生成。

来源与验证

依据 生成实现、配置。本轮未请求服务、删除目录或生成客户端，新增片段未编译。