Microsoft Help Page 与 Swashbuckle Help Page 深度解析

在构建Web API时，为API生成易于理解且功能完备的文档是一个重要的环节。它不仅帮助前端开发者和最终用户理解如何使用API，而且也是后端开发者进行API测试和维护的重要参考。本文将详细介绍两种在.NET中创建Web API帮助文档页面的方法：Microsoft Help Page和Swashbuckle Help Page，并提供具体的代码示例和实现步骤。

在Visual Studio中，打开“工具” > “NuGet包管理器” > “程序包管理器控制台”，然后执行以下命令：

```shell
Install-Package Microsoft.AspNet.WebApi.HelpPage
```

安装完成后，Help Page组件会自动在项目中生成一个名为“HelpPage”的区域（Areas），其中包含了帮助页面的视图和控制器。


在`Global.asax.cs`文件的`Application_Start`方法中注册区域：

```csharp
AreaRegistration.RegisterAllAreas();
```

运行应用程序，通过访问`http://localhost:xxxx/help`来查看自动生成的帮助页面。此时，API的方法列表已经显示出来，但方法的描述可能还是默认的描述。

为了使方法描述与代码注释一致，需要添加XML注释。首先，在项目属性中指定XML文件的输出路径。然后，在`HelpPageConfig.cs`中配置XML文件的路径，以确保帮助页面能够正确地读取注释。

虽然Microsoft Help Page默认不提供测试工具，但你可以通过修改`Api.cshtml`视图来添加一个简单的测试表单，允许用户输入参数并测试API。


通过NuGet安装Swashbuckle：

```shell
Install-Package Swashbuckle.AspNetCore
```

安装后，Swashbuckle将自动配置并生成Swagger UI文档页面，可通过访问`http://localhost:xxxx/swagger`来查看。


与Microsoft Help Page类似，Swashbuckle也需要XML注释来丰富文档内容。在项目属性中指定XML文件的输出路径，并在`Startup.cs`中配置Swashbuckle来引用这些XML文件：

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });
}
```

在使用Swashbuckle时，可能会遇到一些依赖项问题。如果遇到加载程序集失败的异常，确保在`config`文件中添加了对应的依赖项。

Swashbuckle提供了丰富的自定义选项，包括样式和词条的调整。通过编辑`SwaggerConfig.cs`文件，可以进行相应的自定义配置。

Microsoft Help Page和Swashbuckle Help Page都是为.NET Web API生成帮助文档的有效工具。Microsoft Help Page的设置相对复杂，但提供了更多的自定义选项，适合需要高度定制化文档的场景。而Swashbuckle Help Page的搭建更为简单，且自带Swagger UI测试工具，适合快速生成文档和进行API测试。

希望本文能帮助你选择和使用适合自己项目需求的API文档生成工具。如果需要更多示例代码和深入学习，可以访问GitHub上的[相关项目](https://github.com/ErikXu/WebApi.HelpPage)。

进群学习交流加 : mm1552923

如果喜欢我的文章，那么

“在看”和转发是对我最大的支持！