使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
zjqjay
8年前
<p> </p> <p>本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面，并为 API 用户提供丰富的探索、文件和操作体验。</p> <p>源代码: <a href="/misc/goto?guid=4959670755365994220" rel="nofollow,noindex">下载 SwaggerUi_2.zip</a></p> <h3>步骤</h3> <p>在本文中，我们将在 Asp.Net 创建一个简单的 Restful API，并整合 <strong>Swashbuckle 和 Swagger UI</strong> 。本文分为三部分。</p> <ol> <li> <p>创建 Asp.Net Web API项目</p> </li> <li> <p>通过实体数据模型 （.edmx） 和 Scaffold API控件连接到 Sql Server数据库</p> </li> <li> <p>整合 Swashbuckle/Swagger UI框架以描述 API 操作</p> </li> </ol> <h3>创建 Asp.Net Web API 项目</h3> <p>首先创建一个新的“Asp.Net Web应用”，将其命名为“Swagger”</p> <p><img src="https://simg.open-open.com/show/5db56cda05c2f18b201004613044a662.png"></p> <p>从模板中选择 Web API，也就是说， Visual Studio将把 MVC、与Web API相关的文件夹和核心引用添加到我们的应用中。然后，点击“更改权限”，选择“无权限”后点击OK。通过以上设置，我们将跳过项目中与账户相关的控件和视图。</p> <p><img src="https://simg.open-open.com/show/f42f8bd80e24161bd556991f974f15e4.png"></p> <p>执行 Visual Studio 启动程序后，项目文档和文件夹的结构如下：</p> <p><img src="https://simg.open-open.com/show/c17847c587bc34a3733c63c5b74825ac.png"></p> <p>我们将在应用 App_Start 文件夹中将 MVC 控件的路径设置为 RouteConfig.cs ，将Web API控件的路径设置为 WebApiConfig.cs 。</p> <p>注：你可以在该区域看到“帮助页”文件夹。此文件夹将包含 Visual Studio 生成的模型、视图、控件和其他与帮助相关的文档，以描述Web API帮助。我们将在下文对这一问题进行分析。</p> <p><img src="https://simg.open-open.com/show/3681530fb78c273a610eeba7184c4176.png"></p> <p>如果查看 NuGet 包管理器中的“已安装包”，你会发现项目中已经添加了“ <strong>Microsoft Asp.Net Web API 2.2 帮助页</strong> ”包、Razor包和核心包。</p> <p><img src="https://simg.open-open.com/show/16845c3b2deb7fade33ba1037c30b673.png"></p> <h3>通过实体数据模型（edmx）和Scaffold API控件连接到 SQL Server数据库</h3> <p>我们先通过实体数据模型将应用连接到数据库表。首先，创建新的“ADO.NET实体数据模型”项目，在模型文件夹中将其命名为 “SwaggerModel”。</p> <p><a href="/misc/goto?guid=4959670755447445775" rel="nofollow,noindex">附件</a> 为在数据库中创建新表格的脚本文件。</p> <p><img src="https://simg.open-open.com/show/8ec38f90aae48e826cf45592e2c58b89.png"></p> <p>从向导中选择“数据库中的 EF Designer”，并点击“下一步”连接到数据库服务器（此处即为SQL Server）。</p> <p><img src="https://simg.open-open.com/show/e6c6bfd84ece0f9d8d93378b2be157fc.png"></p> <p>在实体数据模型向导页面中，选择连接到 Sql Server，并将连接字符串命名为“SwaggerConStr”，该字符串将保存在web.config文档中。</p> <p><img src="https://simg.open-open.com/show/43b09f04242edfbd8eaeeaca6d257567.png"></p> <p>点击“下一步”，选择实体框架版本（即本文中的6.x）。点击“下一步”，选择EDMX公司表，将其保存在EDMX文档中。</p> <p><img src="https://simg.open-open.com/show/42265ed4df2b3a15ed12c4d3885104a9.png"></p> <p>选择表格，点击“完成”按键，最后会生成POCO类“Company.cs”和数据库配置指令类“SwaggerConStr” 。</p> <p><img src="https://simg.open-open.com/show/fe16f360309363cd0a77a116417f6881.png"></p> <p>现在已经创建了实体数据模型和配置指令，那么我们可以通过Visual Studio支架特性创建新的API控件。但为了充分利用配置指令，在给 API 控件建立支架前，我们应先建立应用。即在建立支架之前，删除控件文件夹中现有的ValuesController.cs。</p> <p>点击控件文件夹，并添加“控件…”，即打开带有各种支架选项的“添加支架”窗口，选择“ <em>* Web API 2 Controller with actions, using Entity Framework（带有动作、使用实体框架的Web API 2控件</em> *”，然后点击“添加”。</p> <p><img src="https://simg.open-open.com/show/1c675cb30166952c60e81dad1eb787a6.png"></p> <p>在添加控件窗口中选择模型（即本文的Company.cs）以及数据配置指令类（SwaggerConStr.cs）。将新控件命名为“CompanyController.cs”，并点击“添加”。</p> <p><img src="https://simg.open-open.com/show/1eef7dee3b3789d7f678ca92ba11f824.png"></p> <p>为每个http 动作（ <strong>GET, PUT, POST and DELETE</strong> ）操作创建的新控件如下：</p> <p><img src="https://simg.open-open.com/show/ca3b10a5722a4fecb3bd0a43f4e55bcc.png"></p> <p>建立和运行应用后，可看到如下截图。你可以在用户界面顶端导航中看到“API”链接，点击后进入“ <strong>Asp.Net API帮助页</strong> ”页面。帮助主页如下所示。</p> <p><img src="https://simg.open-open.com/show/9237dd515cc7ce4e20001d5975b0868d.png"></p> <p>注：为了检查API，应在url中添加“/api/company”，并在浏览器中提交。</p> <p>点击任意操作链接后将显示更多详情，如带有URI、本体参数的“请求”信息、“响应”类型、json或xml等格式。下图为GET方法截图：</p> <p><img src="https://simg.open-open.com/show/549d12e97503d353aef81ff695e6132e.png"></p> <p>虽然Visual Studio团队花费了很大精力为这项服务的消费者展示Web API帮助，但这项服务的薄弱点是用户界面过于基础，而且我们无法使用动作方法。这正是有必要使用 <strong>Swagger UI & Swashbuckle</strong> 的原因。</p> <h3>整合 Swashbuckle/Swagger UI，以描绘API操作</h3> <p>由 <a href="/misc/goto?guid=4958966062191945523" rel="nofollow,noindex">Swagger网站</a> 可知，Swagger是展示RESTful API的简单而强大的方法，它为此API提供了强大的接口。</p> <p>由 <a href="/misc/goto?guid=4959670755557423310" rel="nofollow,noindex">Swashbuckle GitHub</a> 可知，Swashbuckle可将Swagger无缝添加到WebApi中！将ApiExplorer与Swagger/swagge-ui 合并可以给 API 用户带来丰富的探索、文件和操作体验。除Swagger生成器外，Swashbuckle还包含嵌入式版本的swagger-ui。</p> <p>将Swashbuckle添加到 Web API中</p> <p>点击进入“ Manage NuGet Packages…（管理NuGet包）”，并在线搜索“Swashbuckle”。在列表中选择 <strong>Richard Morris</strong> 创建的 <strong>5.2.2版</strong> “ <strong>Swashbuckle - Swagger for Web API</strong> ”，点击安装。</p> <p><img src="https://simg.open-open.com/show/b9d5334d9f2a83c354b363fe457302ba.png"></p> <p><img src="https://simg.open-open.com/show/378e270a94b58412ecedf253345e0951.png"></p> <p>这一操作会将引用添加到“ <strong>Swashbuckle - Swagger for Web API</strong> ”与“ <strong>Swashbuckle.Core - Swagger for Web API</strong> ”中。且后者会在经过依赖检查后添加到我们的项目中。在packages.config中也是如此。</p> <pre> <code class="language-java"><package id="Swashbuckle" version="5.2.2" targetFramework="net45" /> <package id="Swashbuckle.Core" version="5.2.2" targetFramework="net45" /> </code></pre> <p>成功安装后，我们可以在App_Start文件夹中看到一个新的“SwaggerConfig.cs”配置文档，所有Swagger相关配置都会在此进行设置。</p> <p><img src="https://simg.open-open.com/show/498310bd9d5d5034e0313d1a068346e4.png"></p> <p>为了能直接链接到Swagger API 接口，应将下列所有动作链接到“_Layout.cshtml”页面的顶部导航栏。</p> <pre> <code class="language-java"><li>@Html.ActionLink("Swagger Help", "", "Swagger", new { area = "" }, null)</li> </code></pre> <p><img src="https://simg.open-open.com/show/5d61c4cc3fa4743af014bd5284898073.png"></p> <p>现在，建立并运行应用。点击顶部导航的“ <strong>Swagger Help</strong> ”后进入Swagger用户界面。点击列表操作（List Operations），查看所有交互指令操作及相应的动词。</p> <p><img src="https://simg.open-open.com/show/bea5d06d6ffb4ade489e26477f054653.png"></p> <p>点击操作后会显示响应类别。点击“ <strong>Try it out（试试看）!</strong> ”按键后可显示请求URL、响应体、响应代码和响应头等细节。</p> <p>GET操作:</p> <p><img src="https://simg.open-open.com/show/7b324bec449f8a9b2a365287356445e2.png"></p> <p>POST操作细节:</p> <p><img src="https://simg.open-open.com/show/7d2e4ff69be779a44283608142aae511.png"></p> <p>删除操作细节:</p> <p><img src="https://simg.open-open.com/show/be08770450068a7872ca5b3499680046.png"></p> <p>通过Id进行GET操作的细节:</p> <p><img src="https://simg.open-open.com/show/e2cab7901c479ee215f7d509a4558f0a.png"></p> <p>PUT操作细节:</p> <p><img src="https://simg.open-open.com/show/2f2892614dc08df1b5d16d3f88c317ce.png"></p> <p>将XML注解包含在帮助文件中</p> <p>点击进入项目属性，在建立标签下的输出区勾选“ <strong>XML documentation file（XML文档文件）:</strong> ”后，即可在保存文档的二进制文件夹中看到 XML 路径。</p> <p><img src="https://simg.open-open.com/show/4b1b7025c7e06ea23a0f03fd0198e0c1.png"></p> <p>接着打开Swagger配置文档，并添加 “IncludeXmlComments”语句，该语句可将路径从二进制文件夹返回至 XML 文档。</p> <pre> <code class="language-java">private static string GetXmlCommentsPath() { return String.Format(@"{0}\bin\SwaggerUi.XML", System.AppDomain.CurrentDomain.BaseDirectory); } </code></pre> <p>在SwaggerConfig.cs Register静态方法中启用全局配置的方式如下：</p> <pre> <code class="language-java">public static void Register() { var thisAssembly = typeof(SwaggerConfig).Assembly; GlobalConfiguration.Configuration .EnableSwagger(c => { c.SingleApiVersion("v1", "SwaggerUi"); c.IncludeXmlComments(GetXmlCommentsPath()); }) .EnableSwaggerUi(c => { }); } </code></pre> <p>用以下注解编辑控件GET方法，可检查 XML 注解是否运行：</p> <p><img src="https://simg.open-open.com/show/5423b365f36354050456da22a4d5c0ce.png"></p> <p>运行应用，并通过顶部导航栏导航到Swagger帮助页面。随后可看到添加到Swagger帮助页面的XML注解。</p> <p><img src="https://simg.open-open.com/show/0421d8e45af2ef3f00e3a38e655b1831.png"></p> <p>用自定义CSS定制Swagger用户界面</p> <p>Swashbuckle文件规定开发者可用预定义的 “ <strong>InjectStylesheet</strong> ” 方法，将自定义 .css文件作为嵌入式资源注入。我们需要将文件的“ <em>* Logical Name（逻辑名称） *</em> ”作为第二个参数，“media=screen”作为第三个可选参数，当前装配作为第一个参数。</p> <p>在内容文件夹中创建一个新的名为 “myStyle.css”的css文件，并通过添加以下样式将标题默认背景色从绿色改成蓝色。</p> <pre> <code class="language-java">.swagger-section #header { background-color: #0000ff; padding: 14px; } </code></pre> <p>右键点击文档，选择属性，并将其Build操作设置为“ <strong>嵌入式资源</strong> ”</p> <p><img src="https://simg.open-open.com/show/ba779e444a7daa08afaff32c0c31ddea.png"></p> <p>现在，将以下代码添加到 Swagger 配置设置中，以启动用户界面：</p> <pre> <code class="language-java">c.InjectStylesheet(thisAssembly, "SwaggerUi.Content.myStyle.css"); </code></pre> <p>注:样式表单文件的“逻辑名称”。</p> <p>现在运行应用，观察变化。</p> <p><img src="https://simg.open-open.com/show/8a8d7369d4ad5133376aaab124844324.png"></p> <p>用自定义 JavaScript 定制 Swagger UI:</p> <p>Swashbuckle 文件规定开发者可用预定义的 <strong>InjectJavaScript</strong> ” 方法，将自定义的JavaScript 文件作为嵌入式资源注入。我们要将文档的 “ <em>*Logical Name *</em> ”作为第二参数，将当前装配作为第一参数。</p> <p>在脚本文件夹中创建新的 JavaScript 文件 “myScript.js” ，并添加以下基本脚本，这样文件加载时可显示自定义的告警消息。</p> <pre> <code class="language-java">$(document).ready(function () { alert("Hello from custom JavaScript file."); }); </code></pre> <p>右键点击文档，选择属性，将其Build操作设置为“ <strong>嵌入式资源</strong> ”</p> <p><img src="https://simg.open-open.com/show/d2d3e03a995a4c2cce1ff63591c897bf.png"></p> <p>现在将以下代码添加到 Swagger 配置设置中，以启动用户界面：</p> <pre> <code class="language-java">c.InjectJavaScript(thisAssembly, "SwaggerUi.Scripts.myScript.js"); </code></pre> <p>注:Java 描述文件的“逻辑名称”。</p> <p>运行应用，以查看告警消息：</p> <p><img src="https://simg.open-open.com/show/3a44f026105ef247550400e0401020cb.png"></p> <p>注: 我们可以在与API帮助交互之前，通过 “ <strong>InjectJavaScript</strong> ” 特性添加自己的用户界面和行为。请参考 <a href="/misc/goto?guid=4959670755633419199" rel="nofollow,noindex"> <strong>Steve Michelotti</strong> </a> 的文章---" <a href="/misc/goto?guid=4959670755712265416" rel="nofollow,noindex">在使用Swashbuckle的Swagger UI定制认证标头</a> "。</p> <p>最后， SwaggerConfig Register 方法文件如下所示：</p> <pre> <code class="language-java">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"); }); } </code></pre> <p>还有其它的定制方法，笔者今后将更新本文。</p> <p> </p> <p>本文系OneAPM 工程师编译呈现。OneAPM 能助您轻松锁定.NET 应用性能瓶颈，通过强大的 Trace 记录逐层分析，直至锁定行级问题代码。以用户角度展示系统响应速度，以地域和浏览器维度统计用户使用情况。想阅读更多技术文章，请访问OneAPM 官方博客。</p> <p> </p> <p>原文地址： <a href="/misc/goto?guid=4959670755798812631" rel="nofollow,noindex">http://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U#_articleTop</a></p> <p>来自： <a href="/misc/goto?guid=4959670755876831945" rel="nofollow">http://news.oneapm.com/swaggerui-swashbuckle/</a></p> <p>作者： <a href="/misc/goto?guid=4959670755959056062" rel="nofollow,noindex"> <strong>Sreekanth Mothukuru</strong> </a> 2016年2月18日</p>