作者: OneAPM
查看: 1735|回复: 1

[其他] 【WebAPI】使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助...

[复制链接]
OneAPM 发表于 2016-4-14 11:46:31 | 显示全部楼层 |阅读模式
查看: 1735|回复: 1
作者:Sreekanth Mothukuru
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 API 项目
首先创建一个新的“Asp.Net Web应用”,将其命名为“Swagger”
从模板中选择 Web API,然后,点击“更改权限”,选择“无权限”后点击OK。
执行 Visual Studio 启动程序后,项目文档和文件夹的结构如下:
我们将在应用 App_Start 文件夹中将 MVC 控件的路径设置为 RouteConfig.cs ,将Web API控件的路径设置为 WebApiConfig.cs 。
如果查看 NuGet 包管理器中的“已安装包”,你会发现项目中已经添加了“Microsoft Asp.Net Web API 2.2 帮助页”包、Razor包和核心包。

通过实体数据模型(edmx)和Scaffold API控件连接到 SQL Server数据库
我们先通过实体数据模型将应用连接到数据库表。首先,创建新的“ADO.NET实体数据模型”项目,在模型文件夹中将其命名为 “SwaggerModel”。
附件为在数据库中创建新表格的脚本文件。
从向导中选择“数据库中的 EF Designer”,并点击“下一步”连接到数据库服务器(此处即为SQL Server)。
在实体数据模型向导页面中,选择连接到 Sql Server,并将连接字符串命名为“SwaggerConStr”,该字符串将保存在web.config文档中。
点击“下一步”,选择实体框架版本(即本文中的6.x)。点击“下一步”,选择EDMX公司表,将其保存在EDMX文档中。
选择表格,点击“完成”按键,最后会生成POCO类“Company.cs”和数据库配置指令类“SwaggerConStr” 。
点击控件文件夹,并添加“控件…”,即打开带有各种支架选项的“添加支架”窗口,选择“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帮助页”页面。帮助主页如下所示。
下图为GET方法截图:

整合 Swashbuckle/Swagger UI,以描绘API操作将Swashbuckle添加到 Web API中
点击进入“ Manage NuGet Packages…(管理NuGet包)”,并在线搜索“Swashbuckle”。在列表中选择Richard Morris创建的5.2.2版Swashbuckle - Swagger for Web API”,点击安装。
现在,建立并运行应用。点击顶部导航的“Swagger Help”后进入Swagger用户界面。点击列表操作(List Operations),查看所有交互指令操作及相应的动词。
点击操作后会显示响应类别。点击“Try it out(试试看)!”按键后可显示请求URL、响应体、响应代码和响应头等细节。
GET操作:
POST操作细节:
删除操作细节:
通过Id进行GET操作的细节:
PUT操作细节:

右键点击文档,选择属性,并将其Build操作设置为“嵌入式资源

还有其它的定制方法,笔者今后将更新本文。
查看笔者关于 Asp.Net MVC 、 Web API 、 Angular 等的其它文章:

评分

参与人数 1金钱 +1 收起 理由
mumupudding + 1

查看全部评分

回复 论坛版权

使用道具 举报

kuafaaf 发表于 2016-4-15 08:34:41 | 显示全部楼层
虽然是直接从codeproject 翻译 复制过来的, 但是我正好有用, thanks
您需要登录后才可以回帖 登录 | 加入CSkin博客

本版积分规则

QQ|申请友链|小黑屋|手机版|Archiver|CSkin ( 粤ICP备13070794号

Powered by Discuz! X3.2  © 2001-2013 Comsenz Inc.  Designed by ARTERY.cn
GMT+8, 2020-1-26 08:55, Processed in 0.491604 second(s), 33 queries , Gzip On.

快速回复 返回顶部 返回列表