使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件（使用兴奋剂会导致什么后果）

使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件（使用兴奋剂会导致什么后果）

步骤

创建 Asp.Net Web API项目通过实体数据模型 （.edmx） 和 Scaffold API控件连接到 Sql Server数据库整合 Swashbuckle/Swagger UI框架以描述 API 操作

创建 Asp.Net Web API 项目

首先创建一个新的“Asp.Net Web应用”，将其命名为“Swagger”

执行 Visual Studio 启动程序后，项目文档和文件夹的结构如下：

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

注：你可以在该区域看到“帮助页”文件夹。此文件夹将包含 Visual Studio 生成的模型、视图、控件和其他与帮助相关的文档，以描述Web API帮助。我们将在下文对这一问题进行分析。

如果查看 NuGet 包管理器中的“已安装包”，你会发现项目中已经添加了“Microsoft Asp.Net Web API 2.2 帮助页”包、Razor包和核心包。

通过实体数据模型（edmx）和Scaffold API控件连接到 SQL Server数据库

我们先通过实体数据模型将应用连接到数据库表。首先，创建新的“ADO.NET实体数据模型”项目，在模型文件夹中将其命名为 “SwaggerModel”。

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

现在已经创建了实体数据模型和配置指令，那么我们可以通过Visual Studio支架特性创建新的API控件。但为了充分利用配置指令，在给 API 控件建立支架前，我们应先建立应用。即在建立支架之前，删除控件文件夹中现有的ValuesController.cs。

注：为了检查API，应在url中添加“/api/company”，并在浏览器中提交。

虽然Visual Studio团队花费了很大精力为这项服务的消费者展示Web API帮助，但这项服务的薄弱点是用户界面过于基础，而且我们无法使用动作方法。这正是有必要使用Swagger UI & Swashbuckle的原因。

整合 Swashbuckle/Swagger UI，以描绘API操作

将Swashbuckle添加到 Web API中

这一操作会将引用添加到“Swashbuckle - Swagger for Web API”与“Swashbuckle.Core - Swagger for Web API”中。且后者会在经过依赖检查后添加到我们的项目中。在packages.config中也是如此。

成功安装后，我们可以在App_Start文件夹中看到一个新的“SwaggerConfig.cs”配置文档，所有Swagger相关配置都会在此进行设置。

为了能直接链接到Swagger API 接口，应将下列所有动作链接到“_Layout.cshtml”页面的顶部导航栏。

GET操作:

POST操作细节:

删除操作细节:

通过Id进行GET操作的细节:

PUT操作细节:

将XML注解包含在帮助文件中

接着打开Swagger配置文档，并添加 “IncludeXmlComments”语句，该语句可将路径从二进制文件夹返回至 XML 文档。

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

在SwaggerConfig.cs Register静态方法中启用全局配置的方式如下：

public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly; GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "SwaggerUi"); c.IncludeXmlComments(GetXmlCommentsPath()); }) .EnableSwaggerUi(c => { });}

用以下注解编辑控件GET方法，可检查 XML 注解是否运行：

运行应用，并通过顶部导航栏导航到Swagger帮助页面。随后可看到添加到Swagger帮助页面的XML注解。

用自定义CSS定制Swagger用户界面

Swashbuckle文件规定开发者可用预定义的 “InjectStylesheet” 方法，将自定义 .css文件作为嵌入式资源注入。我们需要将文件的“* Logical Name（逻辑名称） *”作为第二个参数，“media=screen”作为第三个可选参数，当前装配作为第一个参数。

在内容文件夹中创建一个新的名为 “myStyle.css”的css文件，并通过添加以下样式将标题默认背景色从绿色改成蓝色。

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

现在，将以下代码添加到 Swagger 配置设置中，以启动用户界面：

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

注:样式表单文件的“逻辑名称”。

现在运行应用，观察变化。

Swashbuckle 文件规定开发者可用预定义的InjectJavaScript” 方法，将自定义的JavaScript 文件作为嵌入式资源注入。我们要将文档的 “*Logical Name *”作为第二参数，将当前装配作为第一参数。

在脚本文件夹中创建新的 JavaScript 文件 “myScript.js” ，并添加以下基本脚本，这样文件加载时可显示自定义的告警消息。

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

现在将以下代码添加到 Swagger 配置设置中，以启动用户界面：

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

注: Java 描述文件的“逻辑名称”。

运行应用，以查看告警消息：

最后， 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"); });}

还有其它的定制方法，笔者今后将更新本文。