介绍

配置

可视化

测试

支持属性

支持XML文档

资源/材料/参考资料

介绍

开发人员通常通过浏览器请求或使用POSTMAN， Advanced Rest Client（ARC）等客户端来测试API 。为了公开API的功能，我们还倾向于通过某些需要额外工作的方法公开方法和描述以及相关的数据结构。为了补充这些功能中的一个或两个， Swagger 变得很方便，它通过配置提供API文档和API测试。

Swagger UI是一种可以跨API生命周期使用的工具。Swagger提供易于导航的文档和/或API资源的可视化，并允许从应用程序本身内部与API交互，从而使开发和测试工作以及最终用户体验无缝顺畅。在本文中，我将讨论如何在API中实现swagger并举例说明Swagger UI的一些用例。我将使用.Net Core 2.0 Web API应用程序并使用Visual Studio 2017 IDE。我已经创建了一个带有单个控制器的示例API应用程序，并且有四个方法作为演示的一部分，可供下载。

Swagger提供最强大，最易用的工具，以充分利用OpenAPI规范。 swagger.io

配置

应用程序上的接线Swagger相当小，可以通过四个简单步骤完成，即安装，导入，注册和端点启用。该软件包可以安装在软件包管理器控制台中，也可以通过转到NuGet软件包管理器菜单。

Install-Package Swashbuckle.AspNetCore

图1：在Package Manager控制台中安装Swagger

安装完成后，必须将Swagger导入Startup.cs。

using Swashbuckle.AspNetCore.Swagger;

然后必须在Startup.cs的ConfigureServices方法中注册Swagger成为服务。

services.AddSwaggerGen(c =>{c.SwaggerDoc(_version, new Info { Title = _applicationName, Version =   _version });});

最后，应用程序必须在Startup.cs的Configure 方法中为swagger启用JSON和UI端点，以便最终用户可以通过Configure UI与API方法交互。

// Enable Swagger JSON endpoint.
app.UseSwagger();
// Enable swagger-ui (HTML, JS, CSS, etc.)
app.UseSwaggerUI(c =>
{c.SwaggerEndpoint($"/swagger/{_version}/swagger.json",${_applicationName} {_version}");
});

代码段1中显示了Startup.cs文件的完整列表。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Swashbuckle.AspNetCore.Swagger;namespace Api
{public class Startup{private string _applicationName;private string _version;public Startup(IConfiguration configuration){Configuration = configuration;}public IConfiguration Configuration { get; }public void ConfigureServices(IServiceCollection services){services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);var config = Configuration.GetSection("ApplicationSetting").Get<ApplicationSetting>();_applicationName = config.Name;_version = config.Version;// Register the Swaggerservices.AddSwaggerGen(c =>{c.SwaggerDoc(_version, new Info { Title = _applicationName, Version = _version });// Set the comments path for the Swagger JSON and UI.var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);c.IncludeXmlComments(xmlPath);});}public void Configure(IApplicationBuilder app, IHostingEnvironment env){if (env.IsDevelopment()){app.UseDeveloperExceptionPage();}else{app.UseHsts();}// Enable Swagger JSON endpoint.app.UseSwagger();// Enable swagger-ui (HTML, JS, CSS, etc.), with the Swagger JSON endpoint.app.UseSwaggerUI(c =>{c.SwaggerEndpoint($"/swagger/{_version}/swagger.json", $"{_applicationName} {_version}");});app.UseHttpsRedirection();app.UseMvc();}}
}

代码段1：Startup.cs的内容

可视化

完成上述四个步骤后， swagger就准备好了。浏览https://localhost:5001/swagger/v1/swagger.json以获取JSON中的数据（在浏览器或客户端，如POSTMAN，Advanced Rest Client（ARC））。返回的JSON对象提供REST方法的规范（由控制器分隔）和API中使用的对象。一个示例响应是代码段2。

{"swagger": "2.0","info": {"version": "v1","title": "SmartStock API"},"paths": {"/api/Stock": {"get": {"tags": ["Stock"],"operationId": "GetStock","consumes": [],"produces": ["text/plain","application/json","text/json"],"parameters": [],"responses": {"200": {"description": "Success","schema": {"uniqueItems": false,"type": "array","items": {"$ref": "#/definitions/Stock"}}}}},"post": {"tags": ["Stock"],"operationId": "PostStock","consumes": ["application/json-patch+json","application/json","text/json","application/*+json"],"produces": ["text/plain","application/json","text/json"],"parameters": [{"name": "stock","in": "body","required": false,"schema": {"$ref": "#/definitions/Stock"}}],"responses": {"200": {"description": "Success","schema": {"$ref": "#/definitions/Stock"}}}}},"/api/Stock/{symbol}": {"get": {"tags": ["Stock"],"operationId": "GetStock","consumes": [],"produces": ["text/plain","application/json","text/json"],"parameters": [{"name": "symbol","in": "path","required": true,"type": "string"}],"responses": {"200": {"description": "Success","schema": {"uniqueItems": false,"type": "array","items": {"$ref": "#/definitions/Stock"}}}}}},"/api/Stock/{id}": {"delete": {"tags": ["Stock"],"operationId": "DeleteStock","consumes": [],"produces": ["text/plain","application/json","text/json"],"parameters": [{"name": "id","in": "path","required": true,"type": "string","format": "uuid"}],"responses": {"200": {"description": "Success","schema": {"type": "boolean"}}}}},"/api/Values": {"get": {"tags": ["Values"],"operationId": "Get","consumes": [],"produces": ["text/plain","application/json","text/json"],"parameters": [],"responses": {"200": {"description": "Success","schema": {"uniqueItems": false,"type": "array","items": {"type": "string"}}}},"deprecated": true},"post": {"tags": ["Values"],"operationId": "Post","consumes": ["application/json-patch+json","application/json","text/json","application/*+json"],"produces": [],"parameters": [{"name": "value","in": "body","required": false,"schema": {"type": "string"}}],"responses": {"200": {"description": "Success"}},"deprecated": true}},"/api/Values/{id}": {"get": {"tags": ["Values"],"operationId": "Get","consumes": [],"produces": ["text/plain","application/json","text/json"],"parameters": [{"name": "id","in": "path","required": true,"type": "integer","format": "int32"}],"responses": {"200": {"description": "Success","schema": {"type": "string"}}},"deprecated": true},"put": {"tags": ["Values"],"operationId": "Put","consumes": ["application/json-patch+json","application/json","text/json","application/*+json"],"produces": [],"parameters": [{"name": "id","in": "path","required": true,"type": "integer","format": "int32"},{"name": "value","in": "body","required": false,"schema": {"type": "string"}}],"responses": {"200": {"description": "Success"}},"deprecated": true},"delete": {"tags": ["Values"],"operationId": "Delete","consumes": [],"produces": [],"parameters": [{"name": "id","in": "path","required": true,"type": "integer","format": "int32"}],"responses": {"200": {"description": "Success"}},"deprecated": true}}},"definitions": {"Stock": {"type": "object","properties": {"id": {"format": "uuid","type": "string"},"ticker": {"type": "string"},"company": {"type": "string"},"price": {"format": "double","type": "number"}}}}
}

代码段2：JSON响应示例

可以通过导航到https://localhost:5001/swagger/index.html来访问Swagger UI ，其中用户可以将JSON响应中可用的相同数据可视化为交互格式。此UI还支持其余方法的实际执行。

图2：在Swagger UI中可视化API

测试

Swagger提供了在没有任何工具的情况下测试API方法的功能。例如，单击 GET（图2中的第一个选项卡）会扩展该方法。通过单击“试一试”然后“执行”，swagger会触发对 /api/stock的'get'方法的调用。请注意，演示应用程序中有一个名为“StockController”的控制器。结果显示在UI中，也可以下载。图3.显示了get方法的结果屏幕。UI中公开的任何方法都可以在UI本身中执行，从而使我们能够直接从API本身测试API。

图3：在Swagger UI中测试API方法

支持属性

默认情况下支持路由属性，Http *属性。图4显示了如何使用HttpGet, HttpPost, HttpDelete修饰的方法反映在Swagger UI中。

图4：反映HTTP属性的Swagger UI

Swagger与.Net中的属性同步。例如，如果使用[Obsolete]属性修饰控制器类，则UI反映控制器“已过时”的事实。图5显示ValuesController标记为“Obsolete”， Swagger UI反映相同且不可点击。当API在不破坏工作代码的情况下逐步取消某些功能时，此功能将变得非常方便。

图5：反映Obsolte属性的Swagger UI

支持XML文档

Swagger支持UI中的文档，其中包含一些配置更改。通过在* .csproj文件中添加以下代码行，将生成XML文档。

<Property Group>....<GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn>
<Property Group>

使用Startup.cs中的以下代码行，在注册时，UI显示XML文档。

services.AddSwaggerGen(c => {   ...var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); c.IncludeXmlComments(xmlPath);
}
);

通过更改使用XML路径，Swagger在UI中公开XML文档。

图6：Swagger UI显示文档

Swagger在所有主流浏览器中都受支持，可在本地或Web环境中使用。UI的外观和风格是可定制的。

我之前展示了它如何在本地机器上运行。Swagger UI在云上运行良好。部署到Azure的相同应用程序， https://smartstockapi.azurewebsites.net/swagger/index.html 和在我的本地计算机上工作的一样。

图7：云中托管的应用程序中的Swagger UI（Azure）

资源/材料/参考资料

swagger.io

开始使用Swashbuckle和ASP.NET Core

GitHub中的代码

原文地址：https://www.codeproject.com/Articles/1271949/Document-and-Test-API-with-Swagger-UI-2

使用Swagger UI的Document和Test API相关推荐

Abp的swagger UI 出现Failed to load API definition.
出现这样的原因,自己应该先查看日志日志截图由日志得出结论,原因:方法的参数在 YT.MasterData.ThirdPartys.DataConvertThirdPartys.MESTranspo ...
SpringMVC+JWT+Swagger UI+RestFul
前言: 其实很早就想写这篇文章了,因为我觉得这会对很多新手有指引作用,当初自己也是瞎子过河的摸索着过来的.目前后台开发比较流行的MVC框架中使用Spring MVC还是比较多的,当然还有Spring ...
Swagger ui接口自动化批量漏洞测试
目录 Swagger介绍 postman 导入Swagger Api 设置Environment 代理设置批量自动化测试结合xray Swagger介绍 Swagger 是一个用于生成.描述和调用 ...
使用 Swagger UI 与 Swashbuckle 创建 RESTful Web API 帮助文件
作者:Sreekanth Mothukuru 2016年2月18日本文旨在介绍如何使用常用的 Swagger 和 Swashbuckle 框架创建描述 Restful API 的交互界面,并为 AP ...
Web API 项目中启用 Swagger UI
Swashbuckle 和 ASP.NET Core 入门 Swagger UI 提供了基于 Web 的 UI,它使用生成的 OpenAPI 规范提供有关服务的信息. Swashbuckle 和 NS ...
swagger ui 怎么输入对象_java swagger ui 添加header请求头参数的方法
我用到的swagger 主要有三款产品,swagger editor,swagger ui 和swagger codegen. swagger editor:主要是一个本地客户端,用来自己添加api, ...
创建Swagger UI文档的步骤
Swagger是一个基于网络的API文档框架.它被用来为API创建交互式文档,这些API是为特定目的而建立的.与其他文档类型相比,Swagger UI文档享有许多优势. 它是开源的使你能够创建和分享 ...
ASP.NET Core 在 Swagger UI 中显示自定义的 Header Token
Swagger 是个好东西,对于前后端分离的网站来说,不仅是提高前后端开发人员沟通效率的利器,也大大方便了后端人员测试 API.有时候,API 中可能需要在 Header 中设置认证参数,比如 aut ...
Flask 系列之构建 Swagger UI 风格的 WebAPI
说明操作系统:Windows 10 Python 版本:3.7x 虚拟环境管理器:virtualenv 代码编辑器:VS Code 实验环境初始化 # 创建项目目录 mkdir helloworl ...

使用Swagger UI的Document和Test API

介绍

配置

可视化

测试

支持属性

支持XML文档

资源/材料/参考资料

使用Swagger UI的Document和Test API相关推荐

最新文章

热门文章