ASP.NET Core 基础知识：API 文档编写 - Telerik.com

文档丰富的 API 对于 Web 项目的成功至关重要。在本文中，我们将深入探讨如何在 ASP.NET Core 中编写 API 文档，涵盖从基础资源到第三方工具的使用方法。通过学习这些内容，您将能够为开发者提供清晰、易于访问的 API 文档，从而提升项目的可维护性和集成效率。

什么是 API 文档及其重要性

应用程序编程接口（API）是两个软件组件通过一组定义（如身份验证、输入和输出数据）和协议（如 REST、SOAP、GraphQL）进行通信的方式。客户端发出请求，服务器返回成功或错误的响应。

虽然 API 的使用可能不需要详细的文档，但提供清晰的 API 文档始终是推荐的做法。文档能够帮助开发者快速了解新 API 的功能和用法，从而加速与其他系统的集成。

可以将 API 文档比作一张城市地图，为开发者提供明确的指引，帮助他们快速找到所需的功能，而无需四处摸索。

创建应用程序并添加文档资源

为了演示 API 文档的编写方法，我们将创建一个 ASP.NET Core Web API 示例应用程序，用于管理事件数据。在开发过程中，我们将探索如何配置和实现文档资源。

先决条件

• .NET 8 或更高版本
• Visual Studio（本文中的一些配置基于 Visual Studio，但也可以通过其他方式完成）

您可以通过以下命令创建基本应用程序，也可以使用 Visual Studio 并选择 ASP.NET Core Web API 模板：

dotnet new webapi -n EventMaster

使用 <summary> 标签编写文档

<summary> 标签是一种注释块，用于对代码元素的功能进行简洁而有意义的描述。它通常位于被记录元素的上方，Visual Studio 的 IntelliSense 会使用这些标签显示类型或成员的额外信息。

创建实体

首先，创建一个名为 Models 的新文件夹，并在其中添加以下类：

public class Event
{
    /// 

    /// 事件的名称
    /// 
    public string Name { get; set; }
}

通过这种方式，开发者可以在代码中直接查看到属性的详细描述。

创建控制器

接下来，创建一个名为 Controllers 的文件夹，并在其中添加控制器类：

[ApiController]
[Route("api/[controller]")]
public class EventsController : ControllerBase
{
    /// 

    /// 获取所有事件
    /// 
    /// 事件列表
    [HttpGet]
    public IEnumerable GetEvents()
    {
        return new List();
    }
}

在这里，每个端点都通过 <summary> 标签进行了功能描述。此外，通过 [ProducesResponseType] 注释，可以指定端点返回的 HTTP 状态码。

配置 Program 类

为了使 API 正常运行，需要配置 Program 类。将以下代码添加到 Program.cs 文件中：

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

生成 XML 文档文件

通过 Visual Studio，可以生成包含 <summary> 标签内容的 XML 文档文件。以下是配置步骤：

1. 右键单击项目，选择“属性”。
2. 在左侧选项卡中选择“生成”。
3. 在“输出”部分，勾选“XML 文档文件”选项，并指定文件路径，例如 EventMasterSwaggerAnnotation.XML。

完成配置后，运行应用程序时，XML 文件会自动生成并保存在指定路径中。

使用 Swagger 查看文档

Swagger 是一个流行的工具，用于生成交互式 API 文档。要启用 Swagger，请安装以下 NuGet 包：

dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore.Annotations

然后，在 Program.cs 文件中添加以下代码：

builder.Services.AddSwaggerGen();
app.UseSwagger();
app.UseSwaggerUI();

运行应用程序后，访问 http://localhost:<port>/swagger，即可查看生成的交互式文档。

使用 Docfx 生成静态 HTML 文档

Docfx 是一个强大的文档生成工具，可以根据代码生成静态 HTML 网站。以下是使用 Docfx 的步骤：

1. 安装 Docfx 工具：

   dotnet tool install -g docfx

2. 在项目根目录中运行以下命令以初始化 Docfx 配置文件：

   docfx init

3. 编辑生成的 docfx.json 文件以匹配项目需求。

4. 运行以下命令生成文档：

   docfx build

5. 通过 http://localhost:8080 访问生成的文档。

结论

清晰的 API 文档对于提升项目质量和加速系统集成至关重要。在本文中，我们介绍了如何使用 ASP.NET Core 的内置工具（如 <summary> 标签和 XML 文档文件）以及第三方工具（如 Swagger 和 Docfx）来生成高质量的 API 文档。

无论是初学者还是经验丰富的开发者，学习如何编写文档都是一项重要的技能。良好的文档不仅能够帮助团队成员理解代码，还能为后续的维护和扩展提供便利。

原文链接: https://www.telerik.com/blogs/aspnet-core-basics-documenting-apis