为使用 .NET 6 开发的 Azure Functions 构建遵循 OpenAPI Specification V3 的内置 API 文档支持

引言

简单来说，OpenAPI 是一种标准方法，定义了如何为你的消费者描述你的 API。 它规定了一些样式，你可以在其中生成一个文档，其中解释了请求格式、响应、错误格式以及开发者在消费你的 API 之前需要了解的几乎所有其他内容。

本文演示了为你的 Azure Functions 实现 Open API 文档的最快方法。 使用这种方法，我们只需要编写非常少的设置代码，因为很多设置都在后台进行，这与其他方法不同。 下面的示例已针对 .NET 6 和 Azure Function V4 显示，但它也应该适用于 .NET Core 3 和 Azure Function V2。

API 文档的主要优势

OpenAPI 标准非常流行，如果你计划将你的 API 暴露给外部消费者，那么几乎可以肯定你将遵循 OpenAPI 进行 API 设计。 OpenAPI 的官方链接可以在下面的链接中找到

• https://spec.openapis.org.cn/oas/latest.html#openapi-specification

此外，一旦你确定了 API 的数据交换格式，如果你生成一个 API 文档并将其与消费者开发者共享，他们就可以开始开发他们的应用程序，而无需担心你的 API 后端实现的完成状态。

Using the Code

本手册中显示的步骤非常简单。 所需代码以屏幕截图的形式共享，也可以在共享的存储库中找到。

步骤 1：创建一个新的 Azure Function 项目

步骤 2：选择带有 OpenAPI 的 HTTP 触发器

步骤 3：将突出显示的软件包更新到最新的 1.3.0 版本

步骤 4：将突出显示的软件包更新到最新的 4.1.1 版本

步骤 5：添加一个新类 OpenApiConfigurationOptions.cs

包含 OpenApiConfigurationOptions 类不是强制性的，但它为你提供了在你的 API 文档中自定义其他信息性内容的灵活性。 也可以更改它为你的文档生成的 Swagger 界面的样式，但这将在另一天讨论。

步骤 6：将 OpenApiConfigurationOptions.cs 文件的正文更新如下

ForceHttp & ForceHttps

如果你没有为你的 Azure Function 配置 HTTPS，则将 ForceHttp 设置为 true & 将 ForceHttps 设置为 false。 这意味着为你的文档生成的 Swagger URL 将仅通过 HTTP 提供。

如果你已经为你的 Azure Function 配置了 HTTPS，则将 ForceHttp 设置为 false & 将 ForceHttps 设置为 true。 这意味着即使他们尝试通过 HTTP 打开，用户也将被重定向到 Swagger URL 的 HTTPS 端点。

如果你已经为你的 Azure Function 配置了 HTTPS，则将 ForceHttp 设置为 false & 将 ForceHttps 设置为 false。 这意味着用户将能够通过 HTTP 以及 HTTPS 访问 Swagger URL 的端点。

使用 OpenApi 注释

我将很快发布一篇单独的文章，介绍如何在你的函数中使用各种可能的注释来自动生成 API 文档。 它们本身非常容易理解，你可以开始尝试使用它们，直到那时为止。

步骤 7：按 F5 并等待 Azure Function 启动

步骤 8：在你的本地浏览器中点击第 5 个 URL，你可以看到你的 Swagger 界面

结论

通过这些简单的步骤，你可以轻松地创建实现 OAS 文档的框架。 *Function1.cs* 文件中 Run 方法之上的 Open API 注释可以帮助我们非常轻松地描述我们的 API。 尝试使用所有可用的注释，看看每个注释都提供什么。 我将单独发布一篇文章来分别解释每一个注释。

关注点

此 Microsoft.Azure.WebJobs.Extensions.OPenApi 的错误消息不是那么容易理解，因此请按照本文中所述的方式保留 OpenAPIConfigurationOptions 类中的代码，你应该一切顺利。

历史

• 2022 年 8 月 6 日：初始版本