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

本文涉及的产品
云数据库 RDS SQL Server,基础系列 2核4GB
RDS SQL Server Serverless,2-4RCU 50GB 3个月
推荐场景:
简介: 本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面,并为 API 用户提供丰富的探索、文件和操作体验。

作者:Sreekanth Mothukuru
2016年2月18日

本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面,并为 API 用户提供丰富的探索、文件和操作体验。

源代码: 下载 SwaggerUi_2.zip

步骤

在本文中,我们将在 Asp.Net 创建一个简单的 Restful API,并整合 Swashbuckle 和 Swagger UI。本文分为三部分。

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

创建 Asp.Net Web 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包和核心包。

通过实体数据模型(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” 。

现在已经创建了实体数据模型和配置指令,那么我们可以通过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的原因。

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

Swagger网站可知,Swagger是展示RESTful API的简单而强大的方法,它为此API提供了强大的接口。

Swashbuckle GitHub可知,Swashbuckle可将Swagger无缝添加到WebApi中!将ApiExplorer与Swagger/swagge-ui 合并可以给 API 用户带来丰富的探索、文件和操作体验。除Swagger生成器外,Swashbuckle还包含嵌入式版本的swagger-ui。

将Swashbuckle添加到 Web API中

点击进入“ 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中也是如此。

<package id="Swashbuckle" version="5.2.2" targetFramework="net45" />
<package id="Swashbuckle.Core" version="5.2.2" targetFramework="net45" />

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

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

<li>@Html.ActionLink("Swagger Help", "", "Swagger", new { area = "" }, null)</li>

现在,建立并运行应用。点击顶部导航的“Swagger Help”后进入Swagger用户界面。点击列表操作(List Operations),查看所有交互指令操作及相应的动词。

点击操作后会显示响应类别。点击“Try it out(试试看)!”按键后可显示请求URL、响应体、响应代码和响应头等细节。

GET操作:

POST操作细节:

删除操作细节:

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

PUT操作细节:

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

点击进入项目属性,在建立标签下的输出区勾选“XML documentation file(XML文档文件):”后,即可在保存文档的二进制文件夹中看到 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;
}

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

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

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

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

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

用自定义 JavaScript 定制 Swagger UI:

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

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

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

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

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

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

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

运行应用,以查看告警消息:

: 我们可以在与API帮助交互之前,通过 “InjectJavaScript” 特性添加自己的用户界面和行为。请参考 Steve Michelotti 的文章---"在使用Swashbuckle的Swagger UI定制认证标头"。

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

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

查看笔者关于 Asp.Net MVC 、 Web API 、 Angular 等的其它文章:

本文系 OneAPM 工程师编译呈现。OneAPM 能助您轻松锁定 .NET 应用性能瓶颈,通过强大的 Trace 记录逐层分析,直至锁定行级问题代码。以用户角度展示系统响应速度,以地域和浏览器维度统计用户使用情况。想阅读更多技术文章,请访问 OneAPM 官方博客

原文地址:http://www.codeproject.com/Articles/1078249/RESTful-Web-API-Help-Documentation-using-Swagger-U#_articleTop

本文转自 OneAPM 官方博客

相关实践学习
使用SQL语句管理索引
本次实验主要介绍如何在RDS-SQLServer数据库中,使用SQL语句管理索引。
SQL Server on Linux入门教程
SQL Server数据库一直只提供Windows下的版本。2016年微软宣布推出可运行在Linux系统下的SQL Server数据库,该版本目前还是早期预览版本。本课程主要介绍SQLServer On Linux的基本知识。 相关的阿里云产品:云数据库RDS&nbsp;SQL Server版 RDS SQL Server不仅拥有高可用架构和任意时间点的数据恢复功能,强力支撑各种企业应用,同时也包含了微软的License费用,减少额外支出。 了解产品详情:&nbsp;https://www.aliyun.com/product/rds/sqlserver
相关文章
|
3月前
|
API
用 Koa 框架实现一个简单的 RESTful API
用 Koa 框架实现一个简单的 RESTful API
|
1月前
|
人工智能 前端开发 API
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
Gemini Coder 是一款基于 Google Gemini API 的 AI 应用生成工具,支持通过文本描述快速生成代码,并提供实时代码编辑和预览功能,简化开发流程。
147 38
Gemini Coder:基于 Google Gemini API 的开源 Web 应用生成工具,支持实时编辑和预览
|
3月前
|
JSON 缓存 JavaScript
深入浅出:使用Node.js构建RESTful API
在这个数字时代,API已成为软件开发的基石之一。本文旨在引导初学者通过Node.js和Express框架快速搭建一个功能完备的RESTful API。我们将从零开始,逐步深入,不仅涉及代码编写,还包括设计原则、最佳实践及调试技巧。无论你是初探后端开发,还是希望扩展你的技术栈,这篇文章都将是你的理想指南。
|
2月前
|
Kubernetes 安全 Devops
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
97 10
有效抵御网络应用及API威胁,聊聊F5 BIG-IP Next Web应用防火墙
|
2月前
|
JSON JavaScript 前端开发
深入浅出Node.js:从零开始构建RESTful API
在数字化时代的浪潮中,后端开发作为连接用户与数据的桥梁,扮演着至关重要的角色。本文将引导您步入Node.js的奇妙世界,通过实践操作,掌握如何使用这一强大的JavaScript运行时环境构建高效、可扩展的RESTful API。我们将一同探索Express框架的使用,学习如何设计API端点,处理数据请求,并实现身份验证机制,最终部署我们的成果到云服务器上。无论您是初学者还是有一定基础的开发者,这篇文章都将为您打开一扇通往后端开发深层知识的大门。
71 12
|
3月前
|
XML JSON 缓存
深入理解RESTful API设计原则与实践
在现代软件开发中,构建高效、可扩展的应用程序接口(API)是至关重要的。本文旨在探讨RESTful API的核心设计理念,包括其基于HTTP协议的特性,以及如何在实际应用中遵循这些原则来优化API设计。我们将通过具体示例和最佳实践,展示如何创建易于理解、维护且性能优良的RESTful服务,从而提升前后端分离架构下的开发效率和用户体验。
|
3月前
|
监控 安全 API
深入浅出:构建高效RESTful API的最佳实践
在数字化时代,API已成为连接不同软件和服务的桥梁。本文将带你深入了解如何设计和维护一个高效、可扩展且安全的RESTful API。我们将从基础概念出发,逐步深入到高级技巧,让你能够掌握创建优质API的关键要素。无论你是初学者还是有经验的开发者,这篇文章都将为你提供实用的指导和启示。让我们一起探索API设计的奥秘,打造出色的后端服务吧!
|
3月前
|
JSON 缓存 测试技术
构建高效RESTful API的后端实践指南####
本文将深入探讨如何设计并实现一个高效、可扩展且易于维护的RESTful API。不同于传统的摘要概述,本节将直接以行动指南的形式,列出构建RESTful API时必须遵循的核心原则与最佳实践,旨在为开发者提供一套直接可行的实施框架,快速提升API设计与开发能力。 ####
|
3月前
|
JavaScript NoSQL API
深入浅出Node.js:从零开始构建RESTful API
在数字化时代的浪潮中,后端开发如同一座灯塔,指引着数据的海洋。本文将带你航行在Node.js的海域,探索如何从一张白纸到完成一个功能完备的RESTful API。我们将一起学习如何搭建开发环境、设计API结构、处理数据请求与响应,以及实现数据库交互。准备好了吗?启航吧!
|
3月前
|
JSON API 数据格式
探索后端开发:从零构建简易RESTful API
在数字时代的浪潮中,后端开发如同搭建一座桥梁,连接着用户界面与数据世界。本文将引导读者步入后端开发的殿堂,通过构建一个简易的RESTful API,揭示其背后的逻辑与魅力。我们将从基础概念出发,逐步深入到实际操作,不仅分享代码示例,更探讨如何思考和解决问题,让每一位读者都能在后端开发的道路上迈出坚实的一步。

热门文章

最新文章

  • 1
    打造高效的Web Scraper:Python与Selenium的完美结合
    14
  • 2
    Burp Suite Professional 2025.2 (macOS, Linux, Windows) - Web 应用安全、测试和扫描
    32
  • 3
    AppSpider Pro 7.5.015 for Windows - Web 应用程序安全测试
    23
  • 4
    【02】客户端服务端C语言-go语言-web端PHP语言整合内容发布-优雅草网络设备监控系统-2月12日优雅草简化Centos stream8安装zabbix7教程-本搭建教程非docker搭建教程-优雅草solution
    57
  • 5
    部署使用 CHAT-NEXT-WEB 基于 Deepseek
    375
  • 6
    【2025优雅草开源计划进行中01】-针对web前端开发初学者使用-优雅草科技官网-纯静态页面html+css+JavaScript可直接下载使用-开源-首页为优雅草吴银满工程师原创-优雅草卓伊凡发布
    27
  • 7
    java spring 项目若依框架启动失败,启动不了服务提示端口8080占用escription: Web server failed to start. Port 8080 was already in use. Action: Identify and stop the process that’s listening on port 8080 or configure this application to listen on another port-优雅草卓伊凡解决方案
    42
  • 8
    零基础构建开源项目OpenIM桌面应用和pc web- Electron篇
    29
  • 9
    【01】客户端服务端C语言-go语言-web端PHP语言整合内容发布-优雅草网络设备监控系统-硬件设备实时监控系统运营版发布-本产品基于企业级开源项目Zabbix深度二开-分步骤实现预计10篇合集-自营版
    22
  • 10
    FastAPI与Selenium:打造高效的Web数据抓取服务 —— 采集Pixabay中的图片及相关信息
    57