Galosys.Foundation.Swashbuckle 26.7.2.1

Galosys.Foundation.Swashbuckle

成熟度: 🟢 稳定 — 生产可用,测试充分,活跃维护

简介

基于 Swashbuckle 的 Swagger/OpenAPI 集成模块,为 ASP.NET Core API 提供自动化的在线文档生成、认证支持和自定义头部扩展。

特性

• 自动生成 RESTful API 和 gRPC 在线文档
• 支持 JWT/Bearer、Basic、ApiKey 三种认证方式
• 自动注入业务头部(租户ID、应用ID、语言、客户端类型)
• 支持请求签名验证(防篡改、防重放)
• 枚举自动显示 DescriptionAttribute 注释
• 支持 Basic 认证保护 Swagger UI
• 自动发现 XML 文档注释
• 支持 [NonSwaggerGen] 特性隐藏指定接口

安装

dotnet add package Galosys.Foundation.Swashbuckle

使用

基础配置

在 appsettings.json 中添加配置:

{
 "Application": {
 "Name": "MyAPI"
 },
 "Swagger": {
 "DisplaySchema": false,
 "AuthEnabled": true,
 "Users": {
 "admin": "admin123"
 }
 }
}

注册服务

// Program.cs
builder.Services.AddSwaggerGen(builder.Configuration);
// 或手动指定名称
builder.Services.AddSwaggerGen("MyAPI");

启用中间件

app.UseSwaggerGen();
// 自定义 UI 配置
app.UseSwaggerGen(opt =>
{
 opt.DefaultModelsExpandDepth(-1);
});

隐藏接口

[NonSwaggerGen]
[ApiController]
public class InternalController : ControllerBase
{
 // 此控制器将不出现在文档中
}

gRPC 文档

自动集成 gRPC Swagger,无需额外配置。

核心类

依赖

• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerGen
• Swashbuckle.AspNetCore.SwaggerUI
• Microsoft.AspNetCore.Grpc.Swagger
• Galosys.Foundation.Core