2016年2月18日
本文旨在介绍如何使用常用的 swagger 和 swashbuckle 框架创建描述 restful api 的交互界面，并为 api 用户提供丰富的探索、文件和操作体验。
在本文中，我们将在 asp.net 创建一个简单的 restful api，并整合 swashbuckle 和 swagger ui。本文分为三部分。
创建 asp.net web api项目
通过实体数据模型 （.edmx） 和 scaffold api控件连接到 sql server数据库
整合 swashbuckle/swagger ui框架以描述 api 操作
首先创建一个新的“asp.net web应用”，将其命名为“swagger”
从模板中选择 web api，也就是说， visual studio将把 mvc、与web api相关的文件夹和核心引用添加到我们的应用中。然后，点击“更改权限”，选择“无权限”后点击ok。通过以上设置，我们将跳过项目中与账户相关的控件和视图。
执行 visual studio 启动程序后，项目文档和文件夹的结构如下：
我们将在应用 app_start 文件夹中将 mvc 控件的路径设置为 routeconfig.cs ，将web api控件的路径设置为 webapiconfig.cs 。
注：你可以在该区域看到“帮助页”文件夹。此文件夹将包含 visual studio 生成的模型、视图、控件和其他与帮助相关的文档，以描述web api帮助。我们将在下文对这一问题进行分析。
如果查看 nuget 包管理器中的“已安装包”，你会发现项目中已经添加了“microsoft asp.net web api 2.2 帮助页”包、razor包和核心包。
我们先通过实体数据模型将应用连接到数据库表。首先，创建新的“ado.net实体数据模型”项目，在模型文件夹中将其命名为 “swaggermodel”。
从向导中选择“数据库中的 ef designer”，并点击“下一步”连接到数据库服务器（此处即为sql server）。
在实体数据模型向导页面中，选择连接到 sql server，并将连接字符串命名为“swaggerconstr”，该字符串将保存在web.config文档中。
点击“下一步”，选择实体框架版本（即本文中的6.x）。点击“下一步”，选择edmx公司表，将其保存在edmx文档中。
选择表格，点击“完成”按键，最后会生成poco类“company.cs”和数据库配置指令类“swaggerconstr” 。
现在已经创建了实体数据模型和配置指令，那么我们可以通过visual studio支架特性创建新的api控件。但为了充分利用配置指令，在给 api 控件建立支架前，我们应先建立应用。即在建立支架之前，删除控件文件夹中现有的valuescontroller.cs。
点击控件文件夹，并添加“控件…”，即打开带有各种支架选项的“添加支架”窗口，选择“web api 2 controller with actions, using entity framework（带有动作、使用实体框架的web api 2控件”，然后点击“添加”。
在添加控件窗口中选择模型（即本文的company.cs）以及数据配置指令类（swaggerconstr.cs）。将新控件命名为“companycontroller.cs”，并点击“添加”。
为每个http 动作（get, put, post and delete）操作创建的新控件如下：
建立和运行应用后，可看到如下截图。你可以在用户界面顶端导航中看到“api”链接，点击后进入“asp.net api帮助页”页面。帮助主页如下所示。
注：为了检查api，应在url中添加“/api/company”，并在浏览器中提交。
点击任意操作链接后将显示更多详情，如带有uri、本体参数的“请求”信息、“响应”类型、json或xml等格式。下图为get方法截图：
虽然visual studio团队花费了很大精力为这项服务的消费者展示web api帮助，但这项服务的薄弱点是用户界面过于基础，而且我们无法使用动作方法。这正是有必要使用swagger ui & swashbuckle的原因。
点击进入“ manage nuget packages…（管理nuget包）”，并在线搜索“swashbuckle”。在列表中选择richard morris创建的5.2.2版 “swashbuckle - swagger for web api”，点击安装。
这一操作会将引用添加到“swashbuckle - swagger for web api”与“swashbuckle.core - swagger for web api”中。且后者会在经过依赖检查后添加到我们的项目中。在packages.config中也是如此。
成功安装后，我们可以在app_start文件夹中看到一个新的“swaggerconfig.cs”配置文档，所有swagger相关配置都会在此进行设置。
为了能直接链接到swagger api 接口，应将下列所有动作链接到“_layout.cshtml”页面的顶部导航栏。
现在，建立并运行应用。点击顶部导航的“swagger help”后进入swagger用户界面。点击列表操作（list operations），查看所有交互指令操作及相应的动词。
点击操作后会显示响应类别。点击“try it out（试试看）!”按键后可显示请求url、响应体、响应代码和响应头等细节。
get操作:
post操作细节:
删除操作细节:
通过id进行get操作的细节:
put操作细节:
点击进入项目属性，在建立标签下的输出区勾选“xml documentation file（xml文档文件）:”后，即可在保存文档的二进制文件夹中看到 xml 路径。
接着打开swagger配置文档，并添加 “includexmlcomments”语句，该语句可将路径从二进制文件夹返回至 xml 文档。
在swaggerconfig.cs register静态方法中启用全局配置的方式如下：
用以下注解编辑控件get方法，可检查 xml 注解是否运行：
运行应用，并通过顶部导航栏导航到swagger帮助页面。随后可看到添加到swagger帮助页面的xml注解。
swashbuckle文件规定开发者可用预定义的 “injectstylesheet” 方法，将自定义 .css文件作为嵌入式资源注入。我们需要将文件的“logical name（逻辑名称）”作为第二个参数，“media=screen”作为第三个可选参数，当前装配作为第一个参数。
在内容文件夹中创建一个新的名为 “mystyle.css”的css文件，并通过添加以下样式将标题默认背景色从绿色改成蓝色。
右键点击文档，选择属性，并将其build操作设置为“嵌入式资源”
现在，将以下代码添加到 swagger 配置设置中，以启动用户界面：
注:样式表单文件的“逻辑名称”。
现在运行应用，观察变化。
swashbuckle 文件规定开发者可用预定义的injectjavascript” 方法，将自定义的javascript 文件作为嵌入式资源注入。我们要将文档的 “logical name ”作为第二参数，将当前装配作为第一参数。
在脚本文件夹中创建新的 javascript 文件 “myscript.js” ，并添加以下基本脚本，这样文件加载时可显示自定义的告警消息。
右键点击文档，选择属性，将其build操作设置为“嵌入式资源”
现在将以下代码添加到 swagger 配置设置中，以启动用户界面：
注: java 描述文件的“逻辑名称”。
运行应用，以查看告警消息：
最后， swaggerconfig register 方法文件如下所示：
还有其它的定制方法，笔者今后将更新本文。
查看笔者关于 asp.net mvc 、 web api 、 angular 等的其它文章：
<a href="http://www.codeproject.com/articles/815916/create-an-asp-net-web-forms-application-using-boot">使用bootstrap和web api创建 asp.net web表单应用</a>
<a href="http://www.codeproject.com/articles/821445/create-a-responsive-html-table-using-footable-and">使用 footable 创建响应式 html 表并使用 handlebars.js 应用客户端绑定</a>
<a href="http://www.codeproject.com/articles/1059870/use-dependency-injector-ninject-to-dynamically-cho">通过依赖注入器 "ninject" 在 orm （实体框架或 dapper ）和数据库（ sql 服务器或oracle 数据库）之间进行动态选择</a>
<a href="http://www.codeproject.com/articles/988129/first-angularjs-application-using-asp-net-mvc-http">使用 asp.net mvc、 $http 和 $window services、ef和 crud 实现的首个 angularjs 应用</a>
<a href="http://www.codeproject.com/articles/1011666/baby-steps-towards-asp-net-web-application-and-see">逐步解决 asp.net 5 web应用并了解新现象</a>