使用 XML 注释和批注来扩充 OpenAPI 文档

4 分钟

在 Swagger UI 中，你可以与 API 的资源交互并将其可视化，而无需访问源代码。 API 的图形表示是根据 OpenAPI 规范自动生成的，这使得其他开发人员可以更轻松地生成使用你的 API 的应用。

Swagger UI 可清晰呈现操作和方法，如下图所示。

Operations of API in Swagger UI.

Swagger UI 还使你能够进行交互，甚至尝试每个操作。

Interaction with API Operation in Swagger UI.

使用 Swashbuckle 和 Swagger 工具自动创建 API 文档可以帮助第三方了解你的 API 资源。但是，如果想进一步提供更详细的信息呢？如果是第一次使用 API，则需要尽可能多的信息。

XML 注释

可通过包含 XML 注释来为代码创建文档。通常会将这些注释直接放在要注释的代码块之前。

/// <summary>
/// Returns a group of Employees matching the given first and last names.
/// </summary>
/// <remarks>
/// Here is a sample remarks placeholder.
/// </remarks>
/// <param name="firstName">The first name to search for</param>
/// <param name="lastName">The last name to search for</param>
/// <returns>A string status</returns>
[HttpGet]
[Route("byname/{firstName}/{lastName}")]
public ActionResult<string> GetByName(string firstName, string lastName)
{
    return "Found another University employee";
}

以下是使用中的 XML 节点：

总结：方法/类/字段的含义或用途的高级总结。
备注：有关方法/类/字段的更多详细信息。
参数：方法的参数及其表示的内容。
返回：方法返回内容的说明。

启用 XML 注释后，Swashbuckle 工具可以将 XML 文档注释包括在 OpenAPI 文档中，并允许你在 Swagger UI 中查看它。

Image showing Swagger UI and added XML Comments.

数据注释

数据注释也一样。只需在模型中添加批注，Swagger 就会扩展 API 文档以将其包含在内。

例如，如果将以下注释添加到控制器：

[Produces("application/json")]

... 你可以在 Swagger UI 中查看添加的信息：

Image showing Swagger UI with added content type added to annotations.

提示

在描述 API 时，应使用多个数据批注。

确定 API 对请求和响应处理哪些 content-types。以下属性指定 API 在两个方向只能使用 application/json 内容类型。
```
[Produces("application/json")]
[Consumes("application/json")]
```
确定可能会返回给调用客户端的潜在 HTTP 响应代码。以下属性展示了返回“404 未找到”的 API。
```
[ProducesResponseType(StatusCodes.Status404NotFound)]
```
你的 API 可能会生成一组标准的响应代码，在这种情况下，可以使用以下属性来指定 200、400 和 404，而不必单独指定每一个。详细了解如何使用 Web API 约定。
```
[ApiConventionMethod(typeof(DefaultApiConventions))]
```
生成 operationId 来显著改进 API 使用体验，包括文档、代码生成以及与其他服务的集成。可以通过在 HTTP 谓词筛选器中添加 Name 属性来自动生成 operationId。
```
[HttpGet("{Height}/{Width}", Name="GetPrice")]
```

使用 XML 注释和批注来扩充 OpenAPI 文档

XML 注释

数据注释

提示

反馈