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

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的工具。
    dotnet add package Swashbuckle.AspNetCore
  2. 配置Swagger服务：
    在Startup.cs文件的ConfigureServices方法中，添加Swagger服务的配置。
    services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});
  3. 添加Swagger中间件：
    在Startup.cs文件的Configure方法中，启用Swagger中间件，并配置UI的端点。
    app.UseSwagger();
app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");
});
  4. 启动应用程序：
    启动应用程序，访问Swagger UI。默认情况下，Swagger UI的地址是/swagger.
    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注释。例如：
    /// <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]：
    用于标注控制器的操作方法，提供对该操作的描述和详细信息。
    [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状态码和响应的类型。
    [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的使用方式。
    [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文档中的呈现。
    [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文档的基本信息，如标题、版本和描述。
    services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1", Description = "Description of your API"});
});
  2. 隐藏Controllers：
    如果你想要隐藏特定的控制器或操作方法，你可以使用IgnoreApi特性或通过配置进行排除。
    services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });c.IgnoreApi(typeof(AdminController)); // 隐藏AdminController
});
  3. 自定义UI外观：
    你可以通过配置Swagger UI的样式和主题，使其符合你的应用程序外观。
    app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");c.InjectStylesheet("/custom.css"); // 引入自定义样式表
});
  4. 自定义Swagger生成规则：
    通过配置DocumentFilter和OperationFilter，你可以编写自定义的Swagger生成规则，以满足特定的需求。
    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配置中引入这个样式表：
    app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "Your API Name V1");c.InjectStylesheet("/custom.css"); // 引入自定义样式表
});
  2. 调整主题和颜色：
    Swagger UI允许你调整主题和颜色，使其符合应用程序的外观。你可以通过配置Theme和SwaggerEndpoint来实现：
    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更符合你的品牌标识。
    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忽略该类或属性。
    [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配置中启用此特性：
    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" /> 来排除特定属性。
    /// <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 进行操作级别的定制。
    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配置中启用自定义过滤器：
    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的访问权限，确保只有授权的用户或系统能够访问。可以通过中间件和过滤器来实现这一点。
    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密钥或身份验证信息。
    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配置。
    #if DEBUG
services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "Your API Name", Version = "v1" });
});
#endif
    这样，只有在Debug模式下才会启用Swagger。
  4. Swagger UI设置密码：
    有些情况下，你可能希望Swagger UI有访问密码。可以通过添加中间件来实现基本的身份验证。
    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; // Unauthorizedreturn;}}await next.Invoke();
});
    上述代码将在访问Swagger UI时检查用户是否已经通过身份验证，未通过身份验证将返回401 Unauthorized。
  5. 定期审查和更新：
    定期审查Swagger文档中的信息，确保它们仍然是准确的，敏感信息没有泄露，并且符合最新的安全标准。

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

4.2 集成身份验证和授权

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

  1. 启用身份验证和授权：
    在ASP.NET Core中，首先确保你的应用程序启用了身份验证和授权。你可以使用内置的身份验证系统或集成第三方身份验证提供者。
    // Startup.cspublic 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能够正确地与身份验证和授权系统交互。
    // Startup.cspublic 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配置中引入该文件。
    // wwwroot/swagger-ui-authorization.jswindow.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 文件：
    // Startup.cspublic 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认证。
    // Startup.cspublic 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。
    // CustomSwaggerDocumentFilter.cspublic 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();// 移除未授权用户的 APIvar 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文档过滤器。
    // Startup.cspublic 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文档。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/news/669666.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

如何训练自己的模型

如何训练自己的模型

无论数据类型或目标如何&#xff0c;用于训练和使用 AutoML 模型的工作流都是相同的&#xff1a; 准备训练数据。 我们需要将需要训练的数据准备为jsonl格式&#xff0c;这种格式的特点就是每一行都是json的格式 {"prompt": "<prompt text>", "…
阅读更多...
机器学习之DeepSequence软件使用学习2-helper模块学习

机器学习之DeepSequence软件使用学习2-helper模块学习

在学习1中粗略地运行了一下软件的例子文件&#xff0c;但其中的很多东西都未能理解。该文中主要是对helper模块中代码的初步注释及学习以求能够熟练使用该软件。 from __future__ import print_function #from __future__ import print_function只在Python 2中有意义。在Pytho…
阅读更多...
java执行可执行文件

java执行可执行文件

文章目录 概要使用Runtime.exec使用ProcessBuilder使用第三方工具包commons-exec.jar 概要 java执行bat或shell脚本的方式主要有三种方式 1、 使用Runtime.exec 2、 使用ProcessBuilder 3、 使用第三方的工具包commons-exec.jar 使用Runtime.exec 在 Java 中&#xff0c;使用…
阅读更多...
【初识爬虫+requests模块】

【初识爬虫+requests模块】

爬虫又称网络蜘蛛、网络机器人。本质就是程序模拟人使用浏览器访问网站&#xff0c;并将需要的数据抓取下来。爬虫不仅能够使用在搜索引擎领域&#xff0c;在数据分析、商业领域都得到了大规模的应用。 URL 每一个URL指向一个资源&#xff0c;可以是一个html页面&#xff0c;一…
阅读更多...
配置git环境与项目创建

配置git环境与项目创建

项目设计 名称&#xff1a;KOB 项目包含的模块 PK模块&#xff1a;匹配界面&#xff08;微服务&#xff09;、实况直播界面&#xff08;WebSocket协议&#xff09; 对局列表模块&#xff1a;对局列表界面、对局录像界面 排行榜模块&#xff1a;Bot排行榜界面 用户中心模块&…
阅读更多...
从Kafka系统中读取消息数据——消费

从Kafka系统中读取消息数据——消费

从Kafka系统中读取消息数据——消费 消费 Kafka 集群中的主题消息检查消费者是不是单线程主题如何自动获取分区和手动分配分区subscribe实现订阅&#xff08;自动获取分区&#xff09;assign&#xff08;手动分配分区&#xff09; 反序列化主题消息反序列化一个类.演示 Kafka 自…
阅读更多...
软件测试学习笔记-使用jmeter进行性能测试

软件测试学习笔记-使用jmeter进行性能测试

性能测试&#xff1a;使用自动化工具&#xff0c;模拟不同的场景&#xff0c;对软件各项性能指标进行测试和评估的过程。 性能测试的目的&#xff1a; 评估当前系统的能力寻找性能瓶颈&#xff0c;优化性能评估软件是否能够满足未来的需要 性能测试和功能测试对比 焦点不同&…
阅读更多...
基于FPGA的图像最近邻插值算法verilog实现,包括tb测试文件和MATLAB辅助验证

基于FPGA的图像最近邻插值算法verilog实现,包括tb测试文件和MATLAB辅助验证

目录 1.算法运行效果图预览 2.算法运行软件版本 3.部分核心程序 4.算法理论概述 5.算法完整程序工程 1.算法运行效果图预览 将FPGA数据导入matlab显示图片&#xff0c;效果如下&#xff1a; 2.算法运行软件版本 vivado2019.2&#xff0c;matlab2022a 3.部分核心程序 ti…
阅读更多...
【开源】SpringBoot框架开发高校学生管理系统

【开源】SpringBoot框架开发高校学生管理系统

目录 一、摘要1.1 项目介绍1.2 项目录屏 二、功能模块2.1 学生管理模块2.2 学院课程模块2.3 学生选课模块2.4 成绩管理模块 三、系统设计3.1 用例设计3.2 数据库设计3.2.1 学生表3.2.2 学院课程表3.2.3 学生选课表3.2.4 学生成绩表 四、系统展示五、核心代码5.1 查询课程5.2 新…
阅读更多...
开源软件：引领技术创新与商业模式转型

开源软件：引领技术创新与商业模式转型

开源软件&#xff1a;引领技术创新与商业模式转型 随着信息技术的飞速发展&#xff0c;开源软件已然成为推动软件行业进步的重要力量。它不仅促进了技术的创新和应用&#xff0c;还催生了多样化的商业模式&#xff0c;深刻影响着全球软件生态系统的演变。 ### 开源软件与技术…
阅读更多...
DQN的理论研究回顾

DQN的理论研究回顾

DQN的理论研究回顾 1. DQN简介 强化学习&#xff08;RL&#xff09;&#xff08;Reinforcement learning: An introduction, 2nd, Reinforcement Learning and Optimal Control&#xff09;一直是机器学习的一个重要领域&#xff0c;近几十年来获得了大量关注。RL 关注的是通…
阅读更多...
服务器和CDN推荐

服务器和CDN推荐

简介 陆云Roovps是一家成立于2021年的主机服务商&#xff0c;主要业务是销售美国服务器、香港服务器及国外湖北十堰高防服务器&#xff0c;还有相关CDN产品。&#xff08; 地址&#xff1a;roovps&#xff09; 一、相关产品
阅读更多...
C语言之数据在内存中的存储

C语言之数据在内存中的存储

目录 1. 整数在内存中的存储2. 大小端字节序和字节序判断什么是大小端&#xff1f;为什么有大小端&#xff1f;练习1练习2练习3练习4练习5练习6 3. 浮点数在内存中的存储浮点数存的过程浮点数取得过程练习题解析 1. 整数在内存中的存储 在讲解操作符的时候&#xff0c;我们已经…
阅读更多...
ffmpeg的使用,安装,抽帧,加水印,截图,生成gif,格式转换,抓屏等

ffmpeg的使用,安装,抽帧,加水印,截图,生成gif,格式转换,抓屏等

实际使用中总结的关于ffmpeg对视频的处理的记录文档 具体信息&#xff1a; http://ffmpeg.org/download.html 官网下载ffmpeg 关于ffmpeg的安装详细步骤和说明 装ffmpeg 方式,Linux和windows下的 http://bbs.csdn.net/topics/390519382 php 调用ffmpeg , http://bbs.csdn.net/t…
阅读更多...
机器学习之正态分布

机器学习之正态分布

正态分布：也称常态分布，又名高斯分布。正态曲线呈钟形，两头低，中间高，左右对称因其曲线呈钟形，也称钟形曲线。若随机变量X服从一个数学期望为μ、方差为 σ 2 \sigma^2 σ2的正态分布，记为N(μ, σ 2 σ^2 σ2)。其概率密度函数为正态分布的期望值μ决定了其位置，其标准…
阅读更多...
（篇九）MySQL常用内置函数

（篇九）MySQL常用内置函数

目录 ⌛数学函数 ⌛字符串函数 ⌛聚合函数 ⌛日期函数 &#x1f4d0;获取当前时间 &#x1f4d0;获取时间的某些内容 &#x1f4d0;​编辑 &#x1f4d0;格式化函数 &#x1f4cf;format类型&#xff1a; ⌛系统信息函数 ⌛类型转换函数 数学函数 字符串函数 聚合函…
阅读更多...
SSH口令问题

SSH口令问题

SSH&#xff08;Secure Shell&#xff09;是目前较可靠、专为远程登录会话和其他网络服务提供 安全性的协议&#xff0c;主要用于给远程登录会话数据进行加密&#xff0c;保证数据传输的安全。 SSH口令长度太短或者复杂度不够&#xff0c;如仅包含数字或仅包含字母等时&#xf…
阅读更多...
html5 audio video

html5 audio video

DOMException: play() failed because the user didn‘t interact with the document first.-CSDN博客 不可用&#xff1a; 可用&#xff1a; Google Chrome Close AutoUpdate-CSDN博客
阅读更多...
[C++] 如何使用Visual Studio 2022 + QT6创建桌面应用

[C++] 如何使用Visual Studio 2022 + QT6创建桌面应用

安装Visual Studio 2022和C环境 [Visual Studio] 基础教程 - Window10下如何安装VS 2022社区版_visual studio 2022 社区版-CSDN博客 安装QT6开源版 下载开源版本QT Try Qt | 开发应用程序和嵌入式系统 | Qt Open Source Development | Open Source License | Qt 下载完成&…
阅读更多...
请问半吊子 C++选手该如何深入学习 C++?

请问半吊子 C++选手该如何深入学习 C++?

请问半吊子 C选手该如何深入学习 C? 在开始前我有一些资料&#xff0c;是我根据网友给的问题精心整理了一份「C的资料从专业入门到高级教程」&#xff0c; 点个关注在评论区回复“888”之后私信回复“888”&#xff0c;全部无偿共享给大家&#xff01;&#xff01;&#xff0…
阅读更多...
最新文章

Copyright @ 2022~2023