Swagger 云 QA Azure 服务架构师 XML 初学者中级开发 ASP.NET C#

在 Azure App Service 上创建具有自动文档记录的 RESTful API

Hugo G Fernandez R

5.00/5 (6投票s)

2020年3月7日

CPOL

6分钟阅读

21019

在本文中，我将逐步解释并展示如何通过 swashbuckle 库为在 ASP 下创建的 RESTful API 实现良好且有用的文档。

引言

Azure 平台在平台即服务 (PaaS) 模型中提供了大量功能，用于托管 Web 应用程序和服务。该平台不仅可以提供托管来执行其应用程序中的逻辑；这还包括一系列强大的机制，用于分别管理 Web 应用程序作为 Web 服务的生命周期的所有方面。

这些关键功能对于通过 Azure 云作为 (PaaS) 创建现代 Web 应用程序至关重要。

当您正在设计基于 Web 应用程序的软件架构时，您需要实现的一个层是 API，它允许您的架构层之间相互通信。无论您的应用程序架构如何，这都是一个很好的机会，您可以实现一个 RESTful API，以便与您各自的 API 使用文档进行通信。

阅读本文后，您可以

创建 RESTful API 应用程序并部署到 Azure 应用服务。
使用开源工具为 API 创建结构良好的文档。

使用 Azure 应用服务创建 API 应用程序有点像创建部署为应用服务的普通 Web 应用程序。您的 API 应用程序可以拥有与普通 Web 应用程序相同的可用选项。

创建和实现 API 应用程序

在 Azure 应用服务中创建 RESTful API 应用程序有多种方法，最常见的方法是通过 Azure 门户或直接从 Visual Studio，在本例中，我们将从 Visual Studio 2019 进行示例

运行 Visual Studio 2019 并选择文件 > 新建 > 项目。
在新项目对话框窗口中，在云类别中选择 ASP.NET Web 应用程序 (.NET Framework) 并单击 下一步。
在新项目配置对话框窗口中，输入项目名称，在磁盘上的物理位置，选择要使用的 .NET Framework 类型，然后单击创建。
在新项目配置对话框窗口中选择 Web API 模板，然后单击创建。

通过这种方式，Visual Studio 创建了一个新的 Web API 项目，在解决方案资源管理器中的文件树中具有以下文件结构

使用 Swashbuckle 生成自动 API 文档

Swashbuckle 是一个非常流行的开源框架，它由一个庞大的工具生态系统组成，用于设计、构建、文档化和使用您的 RESTful API，这使其成为以更自动化方式创建 API 文档的理想替代方案，NuGet 包文档非常完善，因此您可以通过访问文章末尾的 GitHub 项目来查看文档以获取更多详细信息。

Swashbuckle 通过一组 NuGet 包提供：Swashbuckle 和 Swashbuckle Core。然后按照以下步骤将 Swashbuckle 添加到您的 API 项目

使用 NuGet 包控制台中的以下命令安装 NuGet 包，其中包含 Swashbuckle.Core 作为安装时的依赖项
```
Install-Package Swashbuckle
```

NuGet 包还安装了一个初始启动文件或引导程序 (App_Start / SwaggerConfig.cs)，它在使用 WebActivatorEx 启动 API 应用程序时启用 Swagger 路径。您还可以通过修改 SwaggerConfig.cs 文件中的 GlobalConfiguration.Configuration.EnableSwagger 扩展方法来配置 Swashbuckle 选项。您还可以通过添加以下配置从您的 API 操作中排除已标记为过时的操作

  public class SwaggerConfig 
  { 
        public static void Register() 
        { 
   		        var thisAssembly = typeof(SwaggerConfig).Assembly; 
               	GlobalConfiguration.Configuration 
               	.EnableSwagger(c => 
           	    { 
                      ...  
                      ... 

                      //Set this flag to omit schema property descriptions for
                      //any type properties decorated with the Obsolete attribute 

                      c.IgnoreObsoleteProperties(); 

                      ... 
                      ... 

                 }); 
         } 
   }

修改 API 项目中控制器的操作，以包含 swagger 属性，以帮助生成器构建 swagger 元数据。
Swashbuckle 现在已配置为为您的 API 端点生成 Swagger 元数据，并带有一个简单的用户界面来探索列出的 metadata.controller，只需在 Web 浏览器栏中键入 Swagger，然后是 Web 应用程序，即可生成所显示的 UI。

在 Azure 应用服务上发布 RESTful API

到目前为止，我们已经有了一个 API 设计，其基础可以与项目的其他层连接，我们还有一个已经自动生成的文档，通过其控制器的操作充分利用了所有元数据和 API 定义，已经准备好上述所有内容以实现您的 API 应用程序，您需要完成从 Visual Studio 到 Azure 应用服务的发布，以将您的 API 项目部署到云中。

请按照以下步骤从 Visual Studio 部署您的 API 项目

右键单击 Visual Studio 解决方案资源管理器中的项目，然后单击发布。
在发布对话框窗口中，选择左上角的 应用服务，然后选择新建，然后单击发布以转到 Azure 应用服务 设置。
窗口将更改，您将被发送到一个更具体的配置，您必须首先写入要部署在 Azure 应用服务中的应用程序名称，然后选择与您的 Azure 门户中关联的订阅。
接下来，您必须指定 Azure 云中的资源组，Web API 应用程序将作为 Azure 应用服务资源分配给该资源组。
如果您没有任何资源或想创建一个新资源，请单击要创建的新资源组名称。
该资源组通常通过具有或多或少能力的（例如 RAM 使用量或 API 执行所需的处理器数量）可伸缩托管计划来分配计算出的费用容量，默认情况下选择 S1（1 核，1.75 GB RAM），在这种情况下，我们将为了测试目的降低 API 可伸缩性并选择免费成本计划，这是为了共享并且也是一个初始测试环境，当您想进一步扩展应用程序或更改为更高质量或生产环境时，您可以将其优化为适当的计划，以有效地执行您的 API 项目。
一旦在 Azure 应用服务中配置了整个 API 项目环境，就会在 Visual Studio 中创建一个发布配置文件，以便每次您想运行带有新更改的 API 部署时，我们只需使用发布按钮运行发布。Visual Studio 会编译并尝试将 API 项目的所有文件上传到 Azure 云通过 Azure 应用服务，因此您现在可以通过互联网访问其 API。
API 项目发布完成后，它将在新的浏览器窗口中打开，其中将显示初始发布网页。
我们将通过 /Swagger 路由导航到 Swagger 文档，以查看 API 文档的详细信息，此外还将测试通过 API 已经公开的 REST 方法。例如，http://<YOUR-API-APP>.azurewebsites.net/swagger/。