我要招人

C#面试题更新 2026-08-05

请描述在 .NET 开发环境下，利用 OpenAPI 规范或 Swagger 工具来生成和展示 API 文档的具体步骤和方法。

安全意识技术原理方案权衡.NETOpenAPI SpecificationSwagger

考察说明

考查候选人对 .NET 项目中 Swagger/OpenAPI 集成的流程及配置细节的掌握程度。

回答思路

  1. 【回答框架 1】在 .NET 应用程序中，通过向服务容器注册 AddSwaggerGen 服务，并在管道中启用 UseSwagger 和 UseSwaggerUI 中间件，即可基于 XML 注释与路由元数据自动生成 OpenAPI 格式的 API 文档。
  2. 【回答框架 2】XML 注释是文档描述的主要来源，需在项目属性中启用 生成包含 API 文档的 XML 文件，并通过 AddSwaggerGen 配置 IncludeXmlComments 引入注释文件，使接口的摘要、参数和响应说明呈现在 UI 中。
  3. 【回答框架 3】当存在版本控制时，常通过 AddApiVersioning 与 AddSwaggerGen 结合，为不同版本定义独立的 Swagger 文档；也可以在 AddSwaggerGen 中配置多个 OpenApiInfo 实例，并在 UseSwagger 中分别指定版本路由。
  4. 【回答框架 4】为保证接口调用可行性，可通过 AddSecurityDefinition 定义 Bearer Token 或 API Key 的安全方案，并在 OperationFilter 中注入 Authorization 头参数，使 Swagger UI 支持实际的身份验证操作。
  5. 【回答框架 5】在开发与生产环境中，应通过环境判断（如 IsDevelopment）或条件配置决定是否启用 Swagger 端点，避免将 API 文档公开到非预期的网络环境，降低信息泄露风险。
  6. 【关键点 1】核心流程是注册 SwaggerGen 服务并使用 Swagger 中间件，详见官方文档。
  7. 【关键点 2】XML 注释需显式配置 IncludeXmlComments 才可显示方法描述。
  8. 【关键点 3】API 版本控制时需为每个版本注册独立的 Swagger 文档。
  9. 【关键点 4】安全方案需配合 AddSecurityDefinition 与操作过滤器实现 UI 授权。
  10. 【关键点 5】生产环境应谨慎暴露 Swagger 端点。
  11. 【易错点 1】忘记启用 XML 文档生成或未正确配置路径会导致描述缺失。
  12. 【易错点 2】多版本时若未区分 SwaggerDoc 名称会引发冲突。
  13. 【易错点 3】忽略 Swagger 端点安全性可能导致敏感信息泄露。