NICWebApi.Extensions.DynamicAPI 1.0.45

NICWebApi.Extensions.DynamicAPI

DynamicAPI 是一个 ASP.NET Core 扩展包，用于按约定把应用服务暴露为 Web API。

功能

• 支持发现 IDynamicAPI、[DynamicApi] 和显式纳入的服务类型。
• 支持配置 HTTP 方法推断。
• 支持约定式路由和参数绑定。
• 支持重复路由按约定自动消歧。
• 自动补齐 Swagger operationId，便于前端生成稳定方法名。
• 集成 Swagger 和 Swagger UI，并提供可配置 token 持久化能力。
• 支持可选 MiniProfiler 集成。

DynamicAPI 维护时必须保持职责独立：HTTP 方法只由显式谓词或 HttpMethods 推断决定；路由只生成 URL 模板；参数绑定只决定 Query、Route、Body；Swagger operationId 只服务 OpenAPI/前端代码生成，不参与路由或谓词推断。

项目结构

• Abstractions：公共标记接口。
• Attributes：动态 API 和 Swagger 元数据使用的公共特性。
• Conventions：MVC ApplicationModel 约定和控制器发现。
• Extensions：面向 ASP.NET Core 框架对象的扩展入口。
• Options：配置模型和配置辅助方法。
• Swagger：Swagger 注册、UI 模板和过滤器。
• Serialization：JSON 序列化定制。
• Internal：内部工具和实现细节。

命名空间和行为迁移说明见 docs/Migration.md。

更多文档：

• docs/Usage.md：使用方法和常见企业配置。
• docs/Configuration.md：配置默认值和常用预设。
• docs/RouteRules.md：路由生成和参数绑定规则。
• docs/Conventions.md：开发规范和发布检查。
• docs/Migration.md：命名空间和行为迁移说明。

快速开始

using NICWebApi.Extensions.DynamicAPI.Options;

builder.Services
    .AddControllers()
    .AddDynamicWebApi(options =>
    {
        options.HttpMethods.DefaultMethod = "POST";
    });

app.UseDynamicWebApi();
app.MapControllers();

直接实现动态服务标记接口时，引入：

using NICWebApi.Extensions.DynamicAPI.Abstractions;

企业配置示例

默认只允许 GET/POST：

options.HttpMethods.AllowedMethods = new List<string> { "GET", "POST" };
options.HttpMethods.UnsupportedMethodHandling = UnsupportedHttpMethodHandling.UseDefaultMethod;
options.HttpMethods.DefaultMethod = "POST";

不需要修改 Mappings。Mappings 只负责按方法名推断语义 HTTP 方法；AllowedMethods 才负责最终限制，Update / Delete / Patch 会按 UnsupportedMethodHandling 回退到 DefaultMethod。

如果要开放所有 HTTP 方法：

options.HttpMethods.AllowedMethods.Clear();

自定义参数绑定：

options.ParameterBinding.PreserveExplicitBinding = true;
options.ParameterBinding.QueryMethodParameterBinding = DynamicApiParameterBindingSource.Query;
options.ParameterBinding.SimpleTypeParameterBinding = DynamicApiParameterBindingSource.Route;
options.ParameterBinding.ComplexTypeParameterBinding = DynamicApiParameterBindingSource.Body;

显式启用 Swagger UI token 持久化：

options.Swagger.UI.AuthToken.Enabled = true;
options.Swagger.UI.AuthToken.Storage = "sessionStorage";

不修改内置模板，直接配置 Swagger UI 业务拦截器：

options.Swagger.UI.RequestInterceptor = "function(request) { return request; }";
options.Swagger.UI.ResponseInterceptor = "function(response) { return response; }";