.NET Swagger 控制器不显示注释
在使用 .NET 开发 Web API 的过程中，Swagger 是一个非常常用的工具，它可以帮助我们自动生成可视化的 API 文档，方便开发人员和使用者查看和理解 API 的功能和参数。在使用 Swagger 时，我们通常会在控制器的方法上使用注释来描述每个 API 的用途和参数信息。不过有时候我们会遇到一个问题，就是当我们使用 Swagger 生成 API 文档时，控制器的注释信息却没有显示出来。本文将介绍如何解决这个问题。
Swagger 是什么
Swagger 是一种规范和工具，它可以自动生成可视化的 API 文档。通过 Swagger，我们可以方便地查看和测试 API，而不需要直接访问 API 的实际实现。Swagger 支持多种语言和框架，包括 .NET。在 .NET 中，我们可以使用 Swashbuckle 这个开源库来集成 Swagger。
Swashbuckle
Swashbuckle 是一个用于集成 Swagger 的 .NET 库。它提供了一组功能强大的特性，包括自动生成 Swagger 文档、集成 Swagger UI 界面等。在使用 Swashbuckle 时，我们只需要通过几行代码即可将 Swagger 集成到我们的 Web API 项目中。
控制器注释不显示的问题
在使用 Swashbuckle 自动生成 API 文档时，我们通常会在控制器的方法上使用注释来描述 API 的用途和参数信息。不过有时候我们会发现，在生成的 API 文档中，控制器的注释信息却没有显示出来。这可能是由于默认配置导致的，Swagger 在生成文档时没有将注释信息包含进去。
解决方法
要解决控制器注释不显示的问题，我们需要对 Swashbuckle 进行一些配置。具体来说，我们需要指定一个 XML 文档文件，该文件包含了我们编写的所有注释信息。下面是一个示例代码，演示了如何配置 Swashbuckle 并解决注释不显示的问题：
public class SwaggerConfig
{
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "My API");
c.IncludeXmlComments(GetXmlCommentsPath());
})
.EnableSwaggerUi();
}
private static string GetXmlCommentsPath()
{
return string.Format(@"{0}\bin\MyApi.XML",
System.AppDomain.CurrentDomain.BaseDirectory);
}
}
在上面的代码中，我们通过 IncludeXmlComments 方法指定了 XML 文档文件的路径。这个文件应该是在编译项目时自动生成的，其中包含了我们编写的所有注释信息。在 Visual Studio 中，我们可以通过以下步骤来生成 XML 文档文件：
- 打开项目的属性窗口。
- 点击左侧的“生成”选项卡。
- 在右侧的“生成”选项卡中，勾选“XML 文档文件”复选框。
- 保存项目属性。
完成上述步骤后，我们重新运行项目，并使用 Swagger 查看 API 文档，就会发现控制器的注释信息已经显示出来了。
总结
在本文中，我们介绍了如何解决 .NET Swagger 控制器不显示注释的问题。通过配置 Swashbuckle，并指定 XML 文档文件的路径，我们可以将控制器的注释信息包含进 Swagger 生成的 API 文档中。这样，开发人员和使用者就可以更方便地了解每个 API 的用途和参数信息。希望本文对你有所帮助！