使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件

zjqjay 4年前
   <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>