One.OpenApi.UI 1.0.2

OpenApi.UI

OpenApi.UI 是一个基于 ASP.NET Core 的轻量级 API 文档 UI 组件库，为 Swagger/Swashbuckle 提供美观的界面展示。

📖 项目介绍

OpenApi.UI 提供了一个美观的前端界面来展示 OpenAPI/Swagger 文档，支持多版本 API 文档切换、自定义认证等功能。

✨ 特性

• 🎨 美观的现代化 UI 界面
• 🔄 支持多版本 API 文档切换
• 🔐 可配置的认证功能
• 📦 易于集成和使用
• 🚀 基于 .NET 10.0 构建
• 🌐 支持嵌入静态资源
• ⚙️ 可自定义路由路径

📦 安装

通过 NuGet 包管理器（推荐）

Install-Package One.OpenApi.UI

通过 .NET CLI

dotnet add package Install-Package One.OpenApi.UI

🚀 快速开始

1. 配置 Swagger

在 Program.cs 中配置 Swagger：

using OpenApi.UI;
using OpenApi.UI.Interfaces;
using OpenApi.UI.Model;

var builder = WebApplication.CreateBuilder(args);
var services = builder.Services;

// 添加控制器和 Swagger
services.AddControllers();
services.AddEndpointsApiExplorer();
services.AddScoped<IOpenApiUiAuthService, YourAuthService>();

services.AddSwaggerGen(options =>
{
    // 配置第一个 API 版本
    options.SwaggerDoc("v1", new Microsoft.OpenApi.OpenApiInfo
    {
        Title = "My API V1",
        Description = "API 版本 1 的文档",
        Version = "v1"
    });
    
    // 配置第二个 API 版本（可选）
    options.SwaggerDoc("v2", new Microsoft.OpenApi.OpenApiInfo
    {
        Title = "My API V2",
        Description = "API 版本 2 的文档",
        Version = "v2"
    });
});

var app = builder.Build();

app.MapControllers();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(options =>
    {
        options.RouteTemplate = "/openapi/{documentName}.json";
    });
    
    // 配置 OpenApi.UI
    app.UseOpenApiUi(options =>
    {
        // 指定 API 文档路径
        options.DocPaths = ["/openapi/v1.json", "/openapi/v2.json"];
        options.DefaultDocPath = "/openapi/v1.json";
        
        // 配置认证（可选）
        options.Auth = new OpenApiUiAuthConfig()
        {
            Title = "My API",
            Enabled = true,
        };
        
        // 配置路由路径（可选）
        options.RoutePath = "/openapi-ui";
    });
}

app.Run();

2. 实现认证接口（可选）

如果需要认证功能，实现 IOpenApiUiAuthService 接口：

using OpenApi.UI.Interfaces;
using OpenApi.UI.Model;

public class YourAuthService : IOpenApiUiAuthService
{
    public Task<OpenApiUiAuthResponse> AuthenticateAsync(OpenApiUiAuthRequest request)
    {
        // 实现你的认证逻辑，例如验证用户名密码
        var isValidUser = ValidateUser(request.Username, request.Password);
        
        if (isValidUser)
        {
            // 生成 JWT Token
            var token = GenerateJwtToken(request.Username);
            
            // 返回认证响应，设置 Authorization 请求头
            return Task.FromResult(new OpenApiUiAuthResponse
            {
                Headers = new Dictionary<string, string>
                {
                    ["Authorization"] = $"Bearer {token}"
                }
            });
        }
        
        // 认证失败返回空响应或抛出异常
        return Task.FromResult(new OpenApiUiAuthResponse());
    }
    
    public Task<bool> IsAuthenticatedAsync(HttpContext context)
    {
        // 检查认证状态，从请求头中读取 Authorization
        var authHeader = context.Request.Headers["Authorization"].FirstOrDefault();
        
        if (string.IsNullOrEmpty(authHeader))
        {
            return Task.FromResult(false);
        }
        
        // 验证 Token 有效性
        var isAuthenticated = authHeader.StartsWith("Bearer ", StringComparison.OrdinalIgnoreCase)
                              && IsTokenValid(authHeader.Substring(7));
        
        return Task.FromResult(isAuthenticated);
    }
    
    private bool ValidateUser(string username, string password)
    {
        // TODO: 实现用户验证逻辑（如查询数据库）
        return true; // 示例
    }
    
    private string GenerateJwtToken(string username)
    {
        // TODO: 使用 JWT 库生成真实的 Token
        return $"sample-token-for-{username}";
    }
    
    private bool IsTokenValid(string token)
    {
        // TODO: 实现 Token 验证逻辑
        return true; // 示例
    }
}

3. 访问 UI

启动应用后，访问配置的路由路径查看 API 文档：

• 默认路径：/openapi-ui（可通过 RoutePath 配置）

⚙️ 配置选项

OpenApiUiConfig

OpenApiUiAuthConfig

🛠️ 技术栈

• .NET 10.0
• ASP.NET Core
• Swashbuckle (Swagger)
• Razor Class Library

📝 完整示例

详细示例请参考 OpenApiUi.Example 项目。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

前端 UI 组件仓库：https://gitee.com/one529/openapiui

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

感谢所有为这个项目做出贡献的开发者！

注意: 当前版本需要 .NET 10.0 或更高版本。