ASP.NET Core 使用NSwag
内容提要
本文介绍了如何在ASP.NET Core项目中使用NSwag配置和自定义Swagger文档。通过添加NSwag.AspNetCore NuGet包并配置Swagger中间件，可以访问Swagger UI和Swagger JSON。还介绍了如何自定义API描述信息、启用XML描述和数据注解。此外，还介绍了Redoc的使用，它提供了一个更注重文档而不是测试API的页面。
延伸解读
NSwag 与 Microsoft.OpenApi 的命名空间差异
在自定义 API 描述信息时，文章特别提醒 OpenApiInfo 类应使用 NSwag 命名空间下的版本，而非 Microsoft.OpenApi.Models。这一细节容易被忽略，若误用后者可能导致配置不生效或编译错误。读者在参照其他教程时需留意命名空间来源，避免因混用不同库的类而产生困惑。
启用 XML 描述后的警告处理策略
启用 XML 描述后项目会产生警告，文章给出了两种禁用方式：在项目文件中全局禁止，或使用 #pragma warning 预处理指令针对特定成员禁用。全局禁止虽简单但会掩盖其他潜在警告，而局部禁用更精细，适合仅对缺少注释的成员进行处理。读者应根据项目规范权衡选择。
数据注解如何丰富 Swagger UI 信息
通过在 TodoItem 类中添加特性、在控制器上使用 [Produces("application/json")] 和 [ProducesResponseType] 等数据注解，可以明确响应内容类型和状态码。这些注解不仅提升文档可读性，还能帮助前端开发者理解 API 的返回结构。文章展示了注解后 Swagger UI 的生成效果，体现了注解对文档质量的直接影响。
Redoc 与 Swagger UI 的定位区别
Redoc 同样基于 OpenAPI 标准，但更聚焦于文档展示，不提供在页面上测试 API 的交互功能。文章指出访问 Redoc 页面时仅展示 API 信息而无交互，适合需要纯净文档的场景。若团队需要调试接口，Swagger UI 仍是更合适的选择；若仅需对外提供说明文档，Redoc 则更为简洁。
Q&A
如何在ASP.NET Core项目中安装和配置NSwag？
新建项目AspNetCore.NSwag，添加NSwag.AspNetCore NuGet包，然后在Program.cs中配置Swagger中间件。运行后访问/swagger/index.html查看Swagger UI，访问/swagger/v1/swagger.json查看Swagger JSON。
如何自定义NSwag生成的API文档信息，比如作者、许可证？
在Program.cs中更新AddOpenApiDocument方法，使用NSwag命名空间下的OpenApiInfo类来配置API文档信息，如作者、许可证、描述等。
在NSwag中如何启用XML注释来生成API文档？
在项目属性中启用XML文档文件生成，然后在项目文件中会添加相应标签。启用后可能会产生警告，可以通过在项目文件中添加标签禁止整个项目的警告，或使用#pragma warning预处理指令针对特定成员禁用警告。
如何使用数据注解来增强NSwag生成的API文档？
在模型类（如TodoItem）中添加数据注解特性，在API控制器上添加[Produces("application/json")]特性表明响应内容类型，并使用[ProducesResponseType]特性说明API返回的状态码。
Redoc和Swagger UI有什么区别？如何在NSwag中使用Redoc？
Redoc更专注于文档展示，没有提供在页面上测试API的功能，而Swagger UI支持交互测试。在项目中使用Redoc，运行后导航到/redoc地址即可查看，页面上仅展示API信息而无交互功能。
启用XML描述后出现警告，如何禁用这些警告？
有两种方法：在项目文件的Project标签中添加相应标签以禁止整个项目的警告；或者使用#pragma warning预处理指令将特定代码括起来，针对特定成员禁用警告。
