【ASP.NET Core 基础知识】--Web API--Swagger文档生成

喵叔哟2024-02-06 7:09

Swagger是一种用于设计、构建和文档化Web API的开源工具。它提供了一套标准化的规范，使得开发者能够清晰地定义API端点、参数、请求和响应。通过Swagger，用户可以生成具有交互式UI的实时API文档，便于团队协作和第三方开发者理解和使用API。它支持多种编程语言和框架，并提供了丰富的功能，如自动生成代码、请求示例和测试用例。Swagger的目标是简化API开发流程，提高文档质量，并促进开发者、测试人员和其他利益相关方之间的沟通。

Swagger文档在Web API开发中具有重要性，体现在以下几个方面：

  1. 可读性和理解性： Swagger文档提供了清晰、结构化的API文档，使开发者、测试人员和其他团队成员能够轻松理解API的端点、参数、请求和响应结构。
  2. 团队协作： 通过Swagger文档，团队成员能够共享和协作在API的设计和开发过程中。文档作为统一的参考资料，有助于保持团队的一致性和协同作业。
  3. 代码生成和测试： Swagger规范支持自动生成客户端代码和服务端桩代码，提高了开发效率。同时，基于Swagger文档的测试工具可以自动生成测试用例，确保API的正确性和稳定性。
  4. 第三方集成： Swagger文档为第三方开发者提供了详细的API信息，降低了接入和使用API的难度。这有助于促进生态系统的发展，提高API的可用性和可扩展性。
  5. 版本控制和演进： Swagger文档记录了API的版本信息，支持演进过程中的平滑迁移。开发者能够清晰地了解每个版本的变化，有助于升级和维护。

一、ASP.NET Core Web Api中集成Swagger

在ASP.NET Core Web API中集成Swagger是一种有效的方式，通过Swagger能够自动生成、展示并测试API文档。以下是集成Swagger到ASP.NET Core Web API的基本步骤：

  1. 安装Swagger NuGet包：
    使用NuGet包管理器或通过命令行工具，在项目中安装Swashbuckle.AspNetCore包。这个包提供了Swagger的实现和集成到ASP.NET Core的工具。

    bash 复制代码 
    dotnet add package Swashbuckle.AspNetCore

  2. 配置Swagger服务：
    在Startup.cs文件的ConfigureServices方法中，添加Swagger服务的配置。

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});

  3. 添加Swagger中间件：
    在Startup.cs文件的Configure方法中，启用Swagger中间件，并配置UI的端点。

    csharp 复制代码 
    app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
});

  4. 启动应用程序：
    启动应用程序，访问Swagger UI。默认情况下，Swagger UI的地址是/swagger.

    bash 复制代码 
    dotnet run

  5. 访问Swagger UI： 打开浏览器，访问Swagger UI的默认地址：http://localhost:5000/swagger。如果在配置中有自定义的端口或路径，相应地调整访问地址。

  6. 验证生成的文档： 在Swagger UI中，你可以查看API的端点、参数和响应，甚至可以在UI上进行API的测试。

通过以上步骤，你就成功集成了Swagger到ASP.NET Core Web API中。这样的集成不仅提供了方便的文档，还为开发者和团队提供了一个交互式的API测试工具。

二、Web API注释

2.1 XML注释

XML注释是在C#代码中用于生成文档的一种标准化注释方式，特别适用于ASP.NET Core Web API中的控制器和操作方法。通过添加XML注释，可以自动生成Swagger文档并提高API文档的可读性。

以下是如何使用XML注释来注释Web API控制器和操作方法的基本步骤：

  1. 启用XML注释：
    在项目的属性中启用XML文档注释。在Visual Studio中，可以通过项目属性的"生成"选项卡中的"生成XML文档文件"来启用。

  2. 编写XML注释：
    在控制器和操作方法的注释位置添加XML注释。例如：

    csharp 复制代码 
    /// <summary>
/// 用户操作控制器
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    /// <summary>
    /// 获取所有用户信息
    /// </summary>
    /// <returns>用户列表</returns>
    [HttpGet]
    public IEnumerable<User> GetUsers()
    {
        // 实现逻辑
    }

    /// <summary>
    /// 根据用户ID获取用户信息
    /// </summary>
    /// <param name="id">用户ID</param>
    /// <returns>用户信息</returns>
    [HttpGet("{id}")]
    public ActionResult<User> GetUserById(int id)
    {
        // 实现逻辑
    }

    // 其他操作方法的XML注释
}

  3. 生成Swagger文档：
    启动应用程序并访问Swagger UI，你会发现XML注释中的文档已经自动映射到API的相应部分，提高了API文档的质量和可读性。

Tip：XML注释为开发者提供了一种直观而标准化的方式来描述API的各个部分，这对于生成Swagger文档以及其他文档工具都是非常有益的。

2.2 Swagger注解

Swagger注解是在ASP.NET Core Web API中使用Swagger时，通过特定的注解来增强和定制生成的API文档。这些注解可以提供更详细的信息，使生成的Swagger文档更加准确和有用。

以下是一些常用的Swagger注解及其用法：

  1. [SwaggerOperation]：
    用于标注控制器的操作方法，提供对该操作的描述和详细信息。

    csharp 复制代码 
    [HttpGet("{id}")]
[SwaggerOperation(Summary = "Get user by ID", Description = "Retrieve user details by providing user ID.")]
public ActionResult<User> GetUserById(int id)
{
    // 实现逻辑
}

  2. [SwaggerResponse]：
    用于指定操作方法的响应信息，包括HTTP状态码和响应的类型。

    csharp 复制代码 
    [HttpGet("{id}")]
[SwaggerResponse(StatusCodes.Status200OK, "User details retrieved successfully", typeof(User))]
[SwaggerResponse(StatusCodes.Status404NotFound, "User not found")]
public ActionResult<User> GetUserById(int id)
{
    // 实现逻辑
}

  3. [SwaggerRequestExample] 和 [SwaggerResponseExample]：
    用于提供请求和响应的示例，以更清晰地说明API的使用方式。

    csharp 复制代码 
    [HttpPost]
[SwaggerRequestExample(typeof(User), typeof(UserExample))]
[SwaggerResponse(StatusCodes.Status201Created, "User created successfully", typeof(User))]
[SwaggerResponse(StatusCodes.Status400BadRequest, "Invalid user data")]
public ActionResult<User> CreateUser([FromBody] User user)
{
    // 实现逻辑
}

  4. [SwaggerSchema]：
    用于指定模型的额外属性，如title、description等，以定制模型在Swagger文档中的呈现。

    csharp 复制代码 
    [SwaggerSchema(Title = "User Model", Description = "Represents a user in the system.")]
public class User
{
    // 模型属性
}

通过使用这些Swagger注解，开发者可以更灵活地控制生成的Swagger文档的内容和格式，以满足特定的文档需求和团队规范。这对于构建清晰、详细的API文档是非常有帮助的。

2.3 提高文档可读性的最佳实践

提高文档可读性是编写API文档时的关键目标之一，这有助于确保开发者和其他团队成员能够轻松理解和正确使用API。以下是一些提高文档可读性的最佳实践：

  1. 清晰的结构： 组织文档时采用清晰的结构，例如使用标题、子标题、列表等，有助于读者更容易定位和理解信息。
  2. 简洁明了的描述： 使用简洁而明了的语言，避免使用过于复杂的术语，确保文档容易理解。
  3. 实例和示例代码： 提供详细的实例和示例代码，以演示API的使用方式。这有助于开发者更好地理解如何调用API。
  4. 使用注释： 在代码中使用注释，特别是XML注释或Swagger注解，提供关键信息。这些注释可以自动生成API文档。
  5. 使用图表和图形： 使用图表、图形和表格等可视化元素，以更直观地解释API的结构和工作原理。
  6. 错误处理说明： 在文档中详细描述错误处理机制，包括可能发生的错误、错误代码、常见问题和解决方案。
  7. 更新及时： 确保文档保持最新，与实际代码一致。及时更新文档，反映API的最新变更。
  8. 提供搜索功能： 如果文档内容庞大，提供搜索功能有助于用户快速找到他们关心的信息。
  9. 版本控制说明： 如果API有多个版本，文档应明确表明每个版本的变化，以便开发者选择适合其需求的版本。
  10. 附加资源： 在文档中提供附加资源链接，如示例应用程序、教程或其他有助于理解API的资料。
  11. 提供常见问题解答（FAQ）： 收集并回答常见问题，以便用户在遇到问题时能够快速找到解决方案。

通过采用这些最佳实践，可以极大地提高API文档的可读性，从而更好地支持开发者和团队成员使用和维护API。

三、Swagger文档的定制

3.1 修改Swagger配置

在ASP.NET Core Web API中，你可以通过修改Swagger配置来进行Swagger文档的定制。Swashbuckle.AspNetCore提供了一组配置选项，使你能够调整生成的Swagger文档的外观和行为。以下是一些常见的Swagger配置选项和如何修改它们的示例：

  1. 更改Swagger文档信息：
    你可以修改Swagger文档的基本信息，如标题、版本和描述。

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo 
    { 
        Title = "Your API Name", 
        Version = "v1", 
        Description = "Description of your API"
    });
});

  2. 隐藏Controllers：
    如果你想要隐藏特定的控制器或操作方法，你可以使用IgnoreApi特性或通过配置进行排除。

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.IgnoreApi(typeof(AdminController)); // 隐藏AdminController
});

  3. 自定义UI外观：
    你可以通过配置Swagger UI的样式和主题，使其符合你的应用程序外观。

    csharp 复制代码 
    app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // 引入自定义样式表
});

  4. 自定义Swagger生成规则：
    通过配置DocumentFilter和OperationFilter，你可以编写自定义的Swagger生成规则，以满足特定的需求。

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.DocumentFilter<MyCustomDocumentFilter>();
    c.OperationFilter<MyCustomOperationFilter>();
});

以上只是一些定制Swagger文档的基本配置示例。Swashbuckle.AspNetCore提供了更多的配置选项，允许你更精细地调整生成的Swagger文档。通过阅读Swashbuckle.AspNetCore的文档，你可以深入了解可用的配置选项和如何使用它们。

3.2 自定义UI外观

自定义Swagger UI的外观是一种常见的需求，特别是当你希望使API文档与应用程序的整体风格一致时。以下是一些在ASP.NET Core Web API中自定义Swagger UI外观的常见方式：

  1. 引入自定义样式表：
    在Swagger UI中，你可以通过引入自定义的CSS样式表来修改外观。首先，创建一个包含自定义样式的CSS文件（例如，custom.css），然后在Swagger UI配置中引入这个样式表：

    csharp 复制代码 
    app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // 引入自定义样式表
});

  2. 调整主题和颜色：
    Swagger UI允许你调整主题和颜色，使其符合应用程序的外观。你可以通过配置Theme和SwaggerEndpoint来实现：

    csharp 复制代码 
    app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // 引入自定义样式表
    c.ConfigObject.Add("theme", "dark"); // 设置主题
});

    这里，"dark"是一个示例，你可以根据需要选择不同的主题。

  3. 自定义Logo和标题：
    通过配置SwaggerUIOptions，你可以添加自定义Logo和标题，使Swagger UI更符合你的品牌标识。

    csharp 复制代码 
    app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.InjectStylesheet("/custom.css"); // 引入自定义样式表
    c.ConfigObject.Add("theme", "dark"); // 设置主题
    c.DocumentTitle = "Your Custom Title"; // 设置自定义标题
    c.RoutePrefix = "swagger"; // 设置路由前缀
    c.HeadContent = "<link rel='icon' type='image/png' href='/custom-logo.png' />"; // 设置自定义Logo
});

    这里的"/custom-logo.png"是自定义Logo的路径。

通过结合这些配置选项，你可以根据自己的需求完全定制Swagger UI的外观，使其与你的应用程序风格一致。调整样式、主题、颜色和Logo都能够提高文档的吸引力和可读性。

3.3 隐藏敏感信息

在Swagger文档中，有时需要隐藏敏感信息，以确保不会在文档中泄露敏感数据。以下是一些在ASP.NET Core Web API中隐藏敏感信息的常见方式：

  1. 使用 SwaggerIgnoreAttribute：
    你可以创建一个自定义的 SwaggerIgnoreAttribute，并将其应用于类或属性，以指示Swagger忽略该类或属性。

    csharp 复制代码 
    [AttributeUsage(AttributeTargets.Class | AttributeTargets.Property)]
public class SwaggerIgnoreAttribute : Attribute { }

public class User
{
    public int Id { get; set; }
    public string Name { get; set; }

    [SwaggerIgnore]
    public string Password { get; set; }
}

    然后，确保在Swagger配置中启用此特性：

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.SchemaFilter<SwaggerIgnoreFilter>(); // 启用SwaggerIgnoreFilter
});

    SwaggerIgnoreFilter 是一个实现 ISchemaFilter 接口的类，用于过滤Swagger文档中的属性。

  2. 使用 XML 注释隐藏：
    利用 XML 注释，你可以在文档中隐藏或调整某些信息。对于敏感信息，你可以通过添加 <inheritdoc cref="!PropertyName" /> 来排除特定属性。

    csharp 复制代码 
    /// <summary>
/// 用户信息
/// </summary>
public class User
{
    /// <summary>
    /// 用户ID
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// 用户名
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 密码（不在文档中显示）
    /// </summary>
    /// <inheritdoc cref="!Password" />
    public string Password { get; set; }
}

    通过 inheritdoc cref="!Password"，你可以告诉Swagger不要在文档中显示密码属性。

  3. 自定义过滤器：
    通过实现 Swagger 过滤器接口，你可以编写自定义逻辑，控制哪些信息显示在 Swagger 文档中。例如，实现 IOperationFilter 进行操作级别的定制。

    csharp 复制代码 
    public class HidePasswordOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        var ignoredProperties = context.ApiDescription.ActionDescriptor.EndpointMetadata
            .Where(em => em.GetType() == typeof(SwaggerIgnoreAttribute))
            .Select(em => (SwaggerIgnoreAttribute)em);

        foreach (var ignoredProperty in ignoredProperties)
        {
            var propertyToRemove = operation.RequestBody.Content
                .First()
                .Value
                .Schema
                .Properties
                .FirstOrDefault(p => p.Key.ToLower() == ignoredProperty.PropertyName.ToLower());

            if (propertyToRemove.Key != null)
            {
                operation.RequestBody.Content.First().Value.Schema.Properties.Remove(propertyToRemove.Key);
            }
        }
    }
}

    然后，在Swagger配置中启用自定义过滤器：

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.OperationFilter<HidePasswordOperationFilter>(); // 启用自定义过滤器
});

通过以上方法，你可以根据具体需求隐藏或调整Swagger文档中的敏感信息，确保文档不会泄露不必要的细节。

四、安全性和权限控制

4.1 Swagger文档的安全性考虑

确保Swagger文档的安全性是非常重要的，特别是在公共或生产环境中。以下是一些建议，以增强Swagger文档的安全性：

  1. 访问控制：
    限制Swagger UI和Swagger JSON的访问权限，确保只有授权的用户或系统能够访问。可以通过中间件和过滤器来实现这一点。

    csharp 复制代码 
    app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
});

// 添加访问控制中间件
app.Use(async (context, next) =>
{
    // 在这里进行访问控制逻辑
    // 例如，检查用户身份验证信息
    // 如果用户未经授权，可以返回 403 Forbidden 或重定向到登录页
    await next.Invoke();
});

  2. API密钥和身份验证：
    如果你的API需要身份验证，确保Swagger UI也能适应这些要求。你可以在Swagger配置中添加API密钥或身份验证信息。

    csharp 复制代码 
    services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
    c.AddSecurityDefinition("apiKey", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.ApiKey,
        Name = "Authorization",
        In = ParameterLocation.Header,
        Description = "API Key Authorization"
    });
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "apiKey"
                }
            },
            new string[] { }
        }
    });
});

    这将为Swagger UI添加一个API密钥输入框，并在请求中包含身份验证信息。

  3. 隐藏生产环境文档：
    在生产环境中，你可能不希望向外部暴露Swagger文档。你可以通过在启动文件中添加条件检查来隐藏Swagger配置。

    csharp 复制代码 
    #if DEBUG
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});
#endif

    这样，只有在Debug模式下才会启用Swagger。

  4. Swagger UI设置密码：
    有些情况下，你可能希望Swagger UI有访问密码。可以通过添加中间件来实现基本的身份验证。

    csharp 复制代码 
    app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
    c.RoutePrefix = "swagger";
});

app.Use(async (context, next) =>
{
    var endpoint = context.GetEndpoint();
    if (endpoint?.Metadata.GetMetadata<SwaggerEndpointAttribute>() != null)
    {
        var isAuthenticated = context.User.Identity.IsAuthenticated;
        if (!isAuthenticated)
        {
            context.Response.StatusCode = 401; // Unauthorized
            return;
        }
    }
    await next.Invoke();
});

    上述代码将在访问Swagger UI时检查用户是否已经通过身份验证，未通过身份验证将返回401 Unauthorized。

  5. 定期审查和更新：
    定期审查Swagger文档中的信息，确保它们仍然是准确的，敏感信息没有泄露，并且符合最新的安全标准。

通过采用这些安全性考虑措施，可以更好地保护Swagger文档不受未经授权的访问，并确保其中的信息不会泄露敏感信息。

4.2 集成身份验证和授权

在Swagger中集成身份验证和授权是一种重要的安全实践，可以确保只有经过身份验证和授权的用户能够访问API文档。以下是一些在ASP.NET Core Web API中实现Swagger集成身份验证和授权的步骤：

  1. 启用身份验证和授权：
    在ASP.NET Core中，首先确保你的应用程序启用了身份验证和授权。你可以使用内置的身份验证系统或集成第三方身份验证提供者。

    csharp 复制代码 
    // Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // 添加身份验证服务
    services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
    }).AddJwtBearer(options =>
    {
        // 配置 JWT Bearer 认证
        // ...
    });

    // 添加授权服务
    services.AddAuthorization(options =>
    {
        options.AddPolicy("AdminOnly", policy => policy.RequireRole("Admin"));
    });

    // 其他服务配置...
}

  2. 配置 Swagger 认证：
    在Swagger配置中，添加相应的认证配置，以确保Swagger UI能够正确地与身份验证和授权系统交互。

    csharp 复制代码 
    // Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // 配置Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // 添加 JWT Bearer 认证配置
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // 添加授权配置
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // 可选：隐藏 Swagger UI 的 "Authorize" 按钮
        c.AddFilter<HideAuthorizedOperationsFilter>();
    });

    // ...
}

  3. Swagger UI 配置认证按钮：
    为了让Swagger UI显示认证按钮，你可以添加一个JavaScript文件，并在Swagger配置中引入该文件。

    javascript 复制代码 
    // wwwroot/swagger-ui-authorization.js

window.onload = function () {
    const authorizeBtn = document.querySelector(".authorize-wrapper button");

    if (authorizeBtn) {
        authorizeBtn.addEventListener("click", function () {
            const token = prompt("Enter your JWT token");
            if (token) {
                // 将 token 添加到 Authorization 头部
                const input = document.querySelector("input[name='token']");
                if (input) {
                    input.value = "Bearer " + token;
                    input.dispatchEvent(new Event("change"));
                }
            }
        });
    }
};

    在 Swagger 配置中引入 JavaScript 文件：

    csharp 复制代码 
    // Startup.cs

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");

        // 引入自定义 JavaScript 文件
        c.InjectJavascript("/swagger-ui-authorization.js");
    });

    // ...
}

通过这些步骤，Swagger UI 将显示一个 "Authorize" 按钮，用户可以通过输入 JWT Token 进行身份验证。确保你的授权策略与配置中的一致，以限制只有授权用户能够访问 Swagger UI。

4.3 Swagger中的权限控制

在Swagger中进行权限控制是确保只有授权用户能够访问和使用API文档的重要一环。以下是一些在ASP.NET Core Web API中实现Swagger中的权限控制的步骤：

  1. 配置 Swagger 认证：
    在Swagger配置中，首先确保已经配置了相应的身份验证方案，如JWT Bearer认证。

    csharp 复制代码 
    // Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // 配置Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // 添加 JWT Bearer 认证配置
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // 添加授权配置
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // 可选：隐藏 Swagger UI 的 "Authorize" 按钮
        c.AddFilter<HideAuthorizedOperationsFilter>();
    });

    // ...
}

  2. 自定义 Swagger 文档过滤器：
    创建一个自定义的Swagger文档过滤器，该过滤器将根据用户的授权角色过滤掉不可见的API。

    csharp 复制代码 
    // CustomSwaggerDocumentFilter.cs

public class CustomSwaggerDocumentFilter : IDocumentFilter
{
    private readonly IAuthorizationService _authorizationService;

    public CustomSwaggerDocumentFilter(IAuthorizationService authorizationService)
    {
        _authorizationService = authorizationService;
    }

    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        // 获取用户的角色信息，这里的逻辑可以根据实际情况调整
        var userRoles = context.ApiDescriptions
            .SelectMany(apiDesc => apiDesc.ActionDescriptor.EndpointMetadata
                .OfType<AuthorizeAttribute>()
                .SelectMany(attr => attr.Roles.Split(',')))
            .Distinct();

        // 移除未授权用户的 API
        var pathsToRemove = swaggerDoc.Paths
            .Where(pair => pair.Value.Operations.Any(operation =>
                operation.Value.Extensions.ContainsKey("x-roles") &&
                !userRoles.Any(role => operation.Value.Extensions["x-roles"].ToString().Split(',').Contains(role))))
            .Select(pair => pair.Key)
            .ToList();

        foreach (var path in pathsToRemove)
        {
            swaggerDoc.Paths.Remove(path);
        }
    }
}

  3. 使用自定义 Swagger 文档过滤器：
    在Swagger配置中使用刚刚创建的自定义Swagger文档过滤器。

    csharp 复制代码 
    // Startup.cs

public void ConfigureServices(IServiceCollection services)
{
    // ...

    // 添加Swagger服务
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });

        // 添加 JWT Bearer 认证配置
        var securityScheme = new OpenApiSecurityScheme
        {
            Name = "Authorization",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            Description = "Enter 'Bearer {token}' to authenticate."
        };
        c.AddSecurityDefinition("Bearer", securityScheme);

        // 添加授权配置
        var securityRequirement = new OpenApiSecurityRequirement
        {
            { securityScheme, new List<string>() }
        };
        c.AddSecurityRequirement(securityRequirement);

        // 添加自定义 Swagger 文档过滤器
        c.DocumentFilter<CustomSwaggerDocumentFilter>();
    });

    // ...
}

这样，只有具有正确授权角色的用户才能在Swagger UI中看到相关API。确保根据实际的授权策略和角色信息进行适当的调整。这有助于在文档中保护敏感信息，并确保只有经过授权的用户能够查看和使用API。

五、总结

在ASP.NET Core Web API中，通过集成Swagger实现了自动生成API文档的功能。首先，通过安装Swagger NuGet包，配置Swagger服务和中间件，使其与Web API协同工作。通过XML注释和Swagger注解，提供详尽的API信息，包括操作、响应等。为提高文档可读性，采用了结构清晰、简洁描述、实例代码等最佳实践。通过修改Swagger配置和自定义UI外观，使文档更符合团队需求和应用风格。同时，探讨了安全性考虑，包括访问控制、API密钥、Swagger UI设置密码等，以确保文档安全。最后，介绍了权限控制的方法，通过Swagger文档过滤器，只允许具有授权角色的用户查看相关API，进一步保障敏感信息的安全。这些步骤共同构建了一个安全、可读、易用的Swagger文档。

相关推荐
GISer_Jing12 分钟前
前端面试通关：Cesium+Three+React优化+TypeScript实战+ECharts性能方案
前端·react.js·面试
落霞的思绪1 小时前
CSS复习
前端·css
咖啡の猫3 小时前
Shell脚本-for循环应用案例
前端·chrome
uzong5 小时前
面试官：Redis中的 16 库同时发送命令，服务端是串行执行还是并行执行
后端·面试·架构
百万蹄蹄向前冲5 小时前
Trae分析Phaser.js游戏《洋葱头捡星星》
前端·游戏开发·trae
追逐时光者6 小时前
.NET 使用 MethodTimer 进行运行耗时统计提升代码的整洁性与可维护性！
后端·.net
朝阳5816 小时前
在浏览器端使用 xml2js 遇到的报错及解决方法
前端
GIS之路6 小时前
GeoTools 读取影像元数据
前端
ssshooter7 小时前
VSCode 自带的 TS 版本可能跟项目TS 版本不一样
前端·面试·typescript
你的人类朋友7 小时前
【Node.js】什么是Node.js
javascript·后端·node.js
热门推荐
01UV安装并设置国内源02蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接03Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code04KGG转MP3工具|非KGM文件|解密音频05【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）062025最新国内服务器可用docker源仓库地址大全（2025年8月更新）07TRAE 规则（Rules）配置指南：个人习惯、团队规范与最佳实践08NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南09阿里开源首个图像生成基础模型——Qwen-Image本地部署教程，超强中文渲染能力刷新SOTA！10TRAE Rules 实践：为项目配置 6A 工作流