上一篇

下一步

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

已完成

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

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

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 中查看它。

数据注释

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

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

[Produces("application/json")]

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

提示

在描述 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")]
  

继续