ASP.NET Core 中使用Swashbuckle
内容提要
在AspNet Core中使用Swashbuckle可以生成OpenAPI规范和Swagger UI。可以通过配置中间件和添加描述信息来自定义和拓展功能。还可以使用数据注解来指定响应内容和状态码。
延伸解读
Swashbuckle 的三个核心组件
Swashbuckle 由三个包组成：Swashbuckle.AspNetCore.Swagger 提供 Swagger 中间件，用于生成 OpenAPI 规范；Swashbuckle.AspNetCore.SwaggerGen 负责根据代码生成规范文档；Swashbuckle.AspNetCore.SwaggerUI 则提供交互式 UI 界面。理解这三个组件的分工，有助于在自定义时快速定位需要修改的环节。
启用 XML 注释的注意事项
启用 XML 描述后，编译器会为公开成员生成警告，提示缺少注释。可以通过在项目文件中禁止整个项目的警告，或使用 #pragma warning 针对特定成员禁用。生成的 XML 文件需要配置到 Swagger 中加载，且需注意文件路径大小写在 Windows 和 Linux 下的差异，避免部署时加载失败。
数据注解对 API 文档的影响
在模型类上添加数据注解特性，可以丰富 Swagger UI 中显示的参数约束和示例。在控制器上使用 [Produces] 指定响应内容类型，用 [ProducesResponseType] 声明可能返回的状态码，能让生成的 OpenAPI 文档更准确地反映接口行为，方便前端和测试人员理解。
Q&A
Swashbuckle 在 ASP.NET Core 中由哪些核心组件构成？
Swashbuckle 主要有三个核心组件：Swashbuckle.AspNetCore.Swagger、Swashbuckle.AspNetCore.SwaggerGen 和 Swashbuckle.AspNetCore.SwaggerUI。
如何在 ASP.NET Core 项目中安装和配置 Swashbuckle？
首先安装 Swashbuckle.AspNetCore NuGet 包，然后在启动项中配置 Swagger 中间件：在服务中添加 AddSwaggerGen()，并在开发环境下启用中间件 app.UseSwagger() 和 app.UseSwaggerUI()。
Swashbuckle 生成的 OpenAPI 规范默认是什么版本？如何修改？
默认情况下 Swashbuckle 生成的 OpenAPI 规范基于 3.0 版本，可以通过修改版本号来向后兼容其他应用程序。
如何为 Swagger UI 文档添加作者、许可证等基础描述信息？
可以在 Swagger UI 文档上添加基础描述信息，例如作者、许可证、描述等，这些信息会显示在页面上。
怎样启用 XML 描述来生成详细的 API 文档？
在项目中启用 XML 描述，选中后会在项目文件中生成相应标签。启用后可能会产生警告，可以通过在项目文件中添加标签禁止整个项目的警告，或使用 #pragma warning 预处理指令针对特定成员禁用警告。然后在 Swagger 配置中加载生成的 XML 文件，注意大小写区别针对 Windows 和 Linux。
如何使用数据注解来指定 API 的响应内容和状态码？
可以在模型类中添加特性，在 API 控制器上添加 [Produces("application/json")] 特性表明响应内容为 application/json，并使用 ProducesResponseType 特性来说明 API 返回的状态码。
