使用 Swagger UI 和 Swashbuckle 的 RESTful Web API 帮助文档

• 下载源代码 - 5.2 MB

想法

本文旨在教育开发者如何创建交互式界面来表示其 Restful API，从而为 API 消费者提供丰富的发现、文档和沙盒体验。

进程

在本文中，我们将创建一个简单的 ASP.NET Restful API 并集成 Swashbuckle & Swagger UI。文章分为三个部分：

1. 创建 ASP.NET Web API 项目
2. 使用实体数据模型 (.edmx) 连接到 SQL Server 数据库并生成 API 控制器
3. 集成 Swashbuckle/Swagger UI 框架来展示 API 操作

创建 ASP.NET Web API 项目

首先创建一个名为“Swagger”的新“ASP.NET Web 应用程序”。

从模板中选择 Web API，这意味着 Visual Studio 将为我们的应用程序添加 MVC 和 Web API 相关的文件夹和核心引用。另外，点击“更改身份验证”选择“无身份验证”并点击 OK。这样，我们将跳过项目中与帐户相关的控制器和视图。

执行 Visual Studio 引导程序后，这是项目文件和文件夹结构：

在我们的 App_Start 文件夹中，我们将为 MVC 控制器设置 RouteConfig.cs 路由，为 Web API 控制器设置 WebApiConfig.cs 路由。

注意：您可以在 Areas 中看到“HelpPages”文件夹。该文件夹将保存 Visual Studio 生成的用于表示 Web API 帮助的模型、视图、控制器和其他帮助相关文件（我们将在本文稍后讨论）。

如果您在 NuGet 包管理器下看到“已安装的程序包”，您会注意到“Microsoft ASP.NET Web API 2.2 Help Page”包已与 MVC、Razor 和 Core 包一起添加到项目中。

使用实体数据模型 (edmx) 连接到 SQL Server 数据库并生成 API 控制器

首先，让我们使用实体数据模型将应用程序连接到数据库表。在 Models 文件夹中，通过创建一个名为“SwaggerModel”的新项“ADO.NET 实体数据模型”来开始。

下面是用于在数据库中创建新表的脚本文件。

• 下载脚本

从向导中选择“EF Designer from database”，然后点击“Next”连接到数据库服务器（在本例中为 SQL Server）。

在实体数据模型向导屏幕中，选择连接到 SQL Server，并将连接字符串命名为“SwaggerConStr”，该字符串将保存在 web.config 文件中。

点击“Next”选择 Entity Framework 版本（在本例中为 6.x）。点击“Next”选择我们的 Company 表包含在 EDMX 文件中。

选择表并点击“Finish”按钮，这将最终生成我们的 POCO 类“Company.cs”和一个数据库上下文类“SwaggerConStr”。

现在我们的实体数据模型和上下文已创建，我们可以使用 Visual Studio 的脚手架功能创建一个新的 API 控制器。但在生成 API 控制器之前，让我们先构建应用程序以便使用上下文。在生成 API 控制器之前，请删除控制器文件夹中现有的 ValuesController.cs。

右键单击 Controllers 文件夹并添加“Controller…”，这将打开“Add Scaffold”窗口，其中包含各种脚手架选项。选择“Web API 2 Controller with actions, using Entity Framework”并点击“Add”。

在 Add Controller 窗口中，选择 Model（在本例中为 Company.cs）以及 Data Context 类（SwaggerConStr.cs）。将新控制器命名为“CompanyController.cs”并点击“Add”按钮。

新控制器已创建，并包含每个 http 动词（GET、PUT、POST 和 DELETE）的操作。

构建并运行应用程序以查看以下屏幕。从 UI 顶部导航栏，您可以看到“API”链接，它将导航到默认的“ASP.NET API Help Page”屏幕。帮助主页如下所示：

注意：要检查 API，请将“/api/company”添加到 URL 中并在浏览器中提交。

如果您点击任何操作链接，它将显示更多详细信息，例如“Request”信息（包含 URI 和请求正文参数）以及“Response”类型和格式（如 JSON 或 XML）。这是 GET 方法的显示方式：

尽管 Visual Studio 团队为服务使用者提供了 Web API 帮助表示的巨大努力，但其低点在于非常基础的用户界面，并且我们无法尝试操作方法。这时 Swagger UI & Swashbuckle 就派上用场了。

集成 Swashbuckle/Swagger UI 来展示 API 操作

根据 Swagger 网站，Swagger 是您 RESTful API 的简单而强大的表示。它为我们的 API 提供了一个强大的界面。

根据 Swashbuckle GitHub，Swashbuckle 无缝地为 WebApi 项目添加 Swagger！它结合了 ApiExplorer 和 Swagger/swagger-ui，为您的 API 消费者提供丰富的发现、文档和沙盒体验。除了 Swagger 生成器之外，Swashbuckle 还包含一个嵌入式版本的 swagger-ui。

将 Swashbuckle 添加到我们的 Web API

转到“管理 NuGet 程序包…”并在网上搜索“Swashbuckle”。从列表中选择由 Richard Morris 创建、版本号为 **5.2.2** 的“Swashbuckle - Swagger for Web API”并点击 Install。

这将向我们的项目添加“Swashbuckle - Swagger for Web API”以及“Swashbuckle.Core - Swagger for Web API”的引用，同时会检查其依赖项。它将出现在 packages.config 文件中，如下所示：

<package id="Swashbuckle" version="5.2.2" targetFramework="net45" />
<package id="Swashbuckle.Core" version="5.2.2" targetFramework="net45" />

成功安装后，我们会在 App_Start 文件夹中看到一个新的“SwaggerConfig.cs”配置文件。这是我们设置所有 Swagger 相关配置的地方。

为了直接链接到我们的 Swagger API 界面，所有以下操作都链接到“_Layout.cshtml”页面中的顶部导航。

<li>@Html.ActionLink("Swagger Help", "", "Swagger", new { area = "" }, null)</li>

现在构建并运行应用程序。从顶部导航中，点击“Swagger Help”。它将带我们进入 Swagger 用户界面。点击 List Operations 查看所有交互式操作及其相应的动词。

点击操作将显示响应类。点击“Try it out!”按钮将显示其他详细信息，如请求 URL、响应正文、响应代码和响应标头。

GET 操作

POST 操作详细信息

DELETE 操作详细信息

按 ID 获取操作详细信息

PUT 操作详细信息

将 XML 评论包含在帮助文档中

转到项目属性，在 Build 选项卡下的 Output 部分，勾选“XML documentation file:”复选框，您将看到该文件保存在 Bin 文件夹中的 XML 路径。

现在打开 Swagger Config 文件，并添加“IncludeXmlComments”语句，该语句带有一个函数，该函数返回 bin 文件夹中 XML 文件的路径。

private static string GetXmlCommentsPath()
{
    return String.Format
    (@"{0}\bin\SwaggerUi.XML", System.AppDomain.CurrentDomain.BaseDirectory);
}

这是 SwaggerConfig.cs Register static 方法中全局配置的启用方式：

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration
        .EnableSwagger(c =>
        {
            c.SingleApiVersion("v1", "SwaggerUi");
            c.IncludeXmlComments(GetXmlCommentsPath());
        })
        .EnableSwaggerUi(c =>
        {
        });
}

为了检查 XML 评论是否有效，请编辑控制器 Get 方法并添加一些评论，如下所示：

运行应用程序并从顶部导航导航到 Swagger Help 页面。您可以看到 XML 评论已添加到 Swagger Help 页面。

使用我们自己的级联样式表自定义 Swagger UI

Swashbuckle 文档指出，开发人员可以使用预定义方法“InjectStylesheet”将自定义 .css 文件作为嵌入式资源注入。我们需要使用文件的“逻辑名称”作为第二个参数，并使用“media=screen”作为第三个可选参数，并以当前程序集作为第一个参数。

转到 Content 文件夹，创建一个名为“myStyle.css”的新级联样式表文件，并添加以下样式以将标题的默认背景色从 Green 更改为 Blue：

.swagger-section #header {
    background-color: #0000ff;
    padding: 14px;
}

右键单击文件并选择属性，然后将其生成操作设置为“Embedded Resource”。

现在将以下行添加到 SwaggerConfig 设置以启用 UI：

c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css");

注意：样式表文件的“逻辑名称”。

现在运行应用程序以查看更改。

使用我们自己的 JavaScript 自定义 Swagger UI

Swashbuckle 文档指出，开发人员可以使用预定义方法“InjectJavaScript”将自定义 JavaScript 文件作为嵌入式资源注入。我们需要使用文件的“逻辑名称”作为第二个参数，并以当前程序集作为第一个参数。

转到 Scripts 文件夹，创建一个名为“myScript.js”的新 JavaScript 文件，并添加以下基本脚本，以便在文档加载时显示自定义警报消息。

$(document).ready(function () {
    alert("Hello from custom JavaScript file.");
});

右键单击文件并选择属性，将生成操作设置为“Embedded Resource”。

现在将以下行添加到 SwaggerConfig 设置以启用 UI：

c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js");

注意：JavaScript 文件的“逻辑名称”。

运行应用程序以查看警报消息。

注意：我们可以使用“InjectJavaScript”功能在与 API 帮助交互之前添加自己的用户界面和行为。查看 Steve Michelotti 的这篇精彩文章，了解如何“使用 Swashbuckle 自定义 SwaggerUI 中的身份验证标头”。

最后，我们的 SwaggerConfig Register 方法文件如下所示：

public static void Register()
{
    var thisAssembly = typeof(SwaggerConfig).Assembly;

    GlobalConfiguration.Configuration
        .EnableSwagger(c =>
        {
            c.SingleApiVersion("v1", "SwaggerUi");
            c.IncludeXmlComments(GetXmlCommentsPath());
        })
        .EnableSwaggerUi(c =>
        {
            c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css");
            c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js");
        });
}

还有其他几种方法可以实现自定义。我将在以后更新这篇文章。

查看我的其他相关文章，例如 ASP.NET MVC、Web API、Angular 等：

• 使用 Bootstrap 和 Web API 创建 ASP.NET Web Forms 应用程序
• 使用 FooTable 创建响应式 HTML 表格，并使用 Handlebars.Js 应用客户端绑定
• 使用依赖注入器“Ninject”动态选择 ORM（Entity Framework 或 Dapper）和数据库（SQL Server 或 Oracle Database）
• 第一个 AngularJs 应用程序，使用 ASP.NET MVC、$http & $window 服务、EF 和 CRUD 实现
• ASP.NET 5 Web 应用程序的初学者步骤以及新功能介绍

希望您从本文中学到了一些新东西。请随时在下面的“评论”部分“对本文进行评分”、“添加书签”并提供建议。

历史

• 2016 年 2 月 15 日：初始版本
• 2016 年 2 月 18 日：更新了本文，包含了使用自定义级联样式表 (CSS) 自定义 Swagger UI 的说明，并描述了如何包含自定义 JavaScript。