Apq.Cfg.WebApi 1.2.1

Apq.Cfg.WebApi

为 Apq.Cfg 提供 RESTful API 接口，支持远程配置管理，内置 OpenAPI 文档。

📖 在线文档：https://apq-cfg.vercel.app/

安装

dotnet add package Apq.Cfg.WebApi

API 文档 UI

根据目标框架自动选择最适合的 API 文档 UI：

快速开始

方式一：服务集合扩展

using Apq.Cfg;
using Apq.Cfg.WebApi;

var builder = WebApplication.CreateBuilder(args);

// 构建配置
var cfg = new CfgBuilder()
    .AddJsonFile("config.json")
    .AddJsonFile("config.local.json", level: 5, writeable: true, isPrimaryWriter: true)
    .Build();

// 添加服务
builder.Services.AddApqCfgWebApi(cfg, options =>
{
    options.Authentication = AuthenticationType.ApiKey;
    options.ApiKey = "your-secret-key";
});

var app = builder.Build();

app.UseApqCfgWebApi();
app.MapApqCfgWebApi();

app.Run();

方式二：链式调用

using Apq.Cfg;
using Apq.Cfg.WebApi;

var builder = WebApplication.CreateBuilder(args);

// 构建配置并添加 WebApi（链式调用）
var cfg = new CfgBuilder()
    .AddJsonFile("config.json")
    .AddJsonFile("config.local.json", level: 5, writeable: true, isPrimaryWriter: true)
    .Build()
    .AddWebApi(builder.Services, options =>
    {
        options.Authentication = AuthenticationType.ApiKey;
        options.ApiKey = "your-secret-key";
    });

var app = builder.Build();

app.UseApqCfgWebApi();
app.MapApqCfgWebApi();

app.Run();

启动后访问 API 文档 UI 即可查看接口文档。

配置方式

WebApi 选项可以通过两种方式配置：

1. 从 ICfgRoot 读取（推荐）

在配置文件中添加 ApqCfg:WebApi 节：

{
  "ApqCfg": {
    "WebApi": {
      "Authentication": "ApiKey",
      "ApiKey": "your-secret-key",
      "AllowWrite": true,
      "EnableCors": true,
      "CorsOrigins": ["*"]
    }
  }
}

然后直接调用：

builder.Services.AddApqCfgWebApi(cfg);

2. 代码配置（覆盖配置文件）

builder.Services.AddApqCfgWebApi(cfg, options =>
{
    options.Authentication = AuthenticationType.ApiKey;
    options.ApiKey = "your-secret-key";
});

配置优先级（从低到高）：

1. 默认值
2. 从 ICfgRoot 的 ApqCfg:WebApi 节读取的配置
3. configure 回调中的配置

OpenAPI 文档配置

API 文档默认启用，可通过配置调整：

builder.Services.AddApqCfgWebApi(cfg, options =>
{
    options.OpenApiEnabled = true;              // 是否启用 API 文档（默认 true）
    options.OpenApiTitle = "My Config API";     // 文档标题
    options.OpenApiDescription = "配置管理 API"; // 文档描述
    options.OpenApiVersion = "v1";              // API 版本
    options.OpenApiRoutePrefix = "swagger";     // UI 路由前缀
    options.OpenApiShowAuthorizationButton = true; // 显示认证按钮
});

认证方式

// API Key 认证
options.Authentication = AuthenticationType.ApiKey;
options.ApiKey = "your-secret-key";
options.ApiKeyHeaderName = "X-Api-Key";  // 默认

// JWT Bearer 认证
options.Authentication = AuthenticationType.JwtBearer;
options.Jwt = new JwtOptions
{
    Authority = "https://your-auth-server",
    Audience = "your-api"
};

// 无认证（仅开发环境）
options.Authentication = AuthenticationType.None;

API 端点

合并配置（Merged）

配置源（Sources）

管理操作

配置选项

许可证

MIT License