0
点赞
收藏
分享

微信扫一扫

在.NET Core Web API 中应用 Swagger


在.NET Core Web API 中应用 Swagger

  • ​​一、Swagger简介​​
  • ​​1.1 什么是Swagger?​​
  • ​​1.2 Swagger有什么优势?​​
  • ​​1.3 Swagger、OpenAPI3.0、Restful API的区别?​​
  • ​​1.4 Swagger工具​​
  • ​​1.5 Swagger UI工具主要功能​​
  • ​​1.6 Swashbuckle组件​​
  • ​​1.7 TPL​​
  • ​​二、在.NET Core Web API中使用Swagger UI​​
  • ​​2.1 创建一个WebAPI项目​​
  • ​​2.2 下载、安装、引入`Swashbuckle.AspNetCore`包​​
  • ​​2.3 配置Swagger中间件(注册 Swagger 服务)​​
  • ​​2.4 启用Swagger中间件​​
  • ​​2.5 运行项目​​
  • ​​2.6 如果想每次运行都默认直接到Swagger的页面​​
  • ​​2.7 描述信息详细讲解​​
  • ​​三、启用XML注释​​
  • ​​3.1 双击解决方案​​
  • ​​3-2 然后进入这个页面,加上这个代码​​
  • ​​3-3 在`Startup.cs`文件中的`ConfigureService`类中注册读取XML信息的Swagger​​
  • ​​四、实例​​
  • ​​4.1 写一个实例:在`WeatherForecastController`控制器中写一个方法​​
  • ​​4.2 写上以下代码然后开始请求​​
  • ​​4.3 可以看到 XML注释 起作用了,然后调用也成功了​​
  • ​​五 .Net Core3.1 swagger 文档添加 不用 xml 配置​​

一、Swagger简介

1.1 什么是Swagger?

  • Swagger是一个规范且完整的框架,用于生成、描述、调试和可视化 Restfull 风格的Web服务
  • Swagger的目标是对Rest API定义一个标准且和语言无关的接口,可以让人和计算机拥有无需访问源码、文档或网络流量监控就可以发现和连接服务的能力。当通过Swagger进行正确定义,用于可以理解远程服务并使用最少逻辑与远程服务进行交互。与为底层编程所实现的接口类似,Swagger消除了调用服务时可能会有的猜测

1.2 Swagger有什么优势?

  • 支持API自动生成同步的在线文档:使用Swagger后可以直接通过代码生成文档,不需要自己去手动编写接口文档了,对程序员来说是非常方便
  • 提供Web页面在线测试API:光有文档还不够,Swagger生成的文档还支持在线测试。参数和格式都一定定义好了,直接在界面上输出参数对应的值即可在先测试接口
  • Swagger可以生成客户端SDK代码用于各种不同平台的实现
  • Swagger文件可以在许多不同的平台上从代码注释中自动生成
  • Swagger有一个强大的社区,里面有许多强悍的贡献者

1.3 Swagger、OpenAPI3.0、Restful API的区别?

  • Open API=规范:OpenAPI是规范的正式名称。该规范的开发时由OpenAPI Initative推动的。该提倡涉及不同领域的30个组织——包括Microsoft、Google、IBM和CapitalOne
  • Swagger=实现OpenAPI规范的工具之一
  • RestfulAPI=一种WebAPI设计架构风格。其中Rest即Represntaional State Transfer的缩写,可以翻译为"状态表述转换"。是目前比较成熟的一套互联网应用程序的API设计架构风格OpenAPI规范即是这个架构风格的具体实现规范

1.4 Swagger工具

在.NET Core Web API 中应用 Swagger_.net core3.1

1.5 Swagger UI工具主要功能

  • 接口的文档在线自动生成
  • 功能测试等

1.6 Swashbuckle组件

  • Swashbuckle是.NET Core中对Swagger的封装,他有2个核心组件:
  • Swashbuckle.SwaggerGen:提供生成对象、方法、返回类型等JSON Swagger文档的功能
  • Swashbuckle.SwaggerUI:是一个嵌入式版本的SwaggerUI工具,使用Swagger UI强大的富文本表现形式可定制化的来描述Web API的功能,并且包含内置的公共方法测试工具

1.7 TPL

  • 任务并行库(TPL)是​​System.Threading.Tasks​​命名空间中的一组公共类型和API
  • TPL动态的扩展并发度,以最有效的使用可用的处理器。通过使用TPL,您可以最大限度的提高代码的性能,同时专注于您的代码业务
  • 从.NETFramework4开始,TPL是编写多线程和并行代码的首选方式

二、在.NET Core Web API中使用Swagger UI

2.1 创建一个WebAPI项目

在.NET Core Web API 中应用 Swagger_.net core3.1_02

2.2 下载、安装、引入​​Swashbuckle.AspNetCore​​包

  • 打开Nuget包管理器,搜索​​Swashbuckle.AspNetCore​​包,点击【安装】即可

2.3 配置Swagger中间件(注册 Swagger 服务)

  • 在​​Startup.cs​​​文件中的​​ConfigureService​​类中引入命名空间,并注册 Swagger 服务并配置文档信息

//引入命名空间
using Microsoft.OpenApi.Models;

//注册Swagger
services.AddSwaggerGen(u =>
{
u.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "Ver:1.0.0",//版本
Title = "后台管理系统",//标题
Description = "后台管理系统:包括学生信息、部门管理等。",//描述
Contact = new Microsoft.OpenApi.Models.OpenApiContact
{
Name = "UserName",
Email = "***@hotmail.com"
}
});
});

  • 如果安装的 ​​Swashbuckle.AspNetCore​​​ Nuget 包版本 <= 3.0.0,写法略有不同。将 ​​OpenApiInfo​​ 替换成 【Info】 即可

services.AddSwaggerGen(x =>
{
x.SwaggerDoc("v1", new Info() { Title = "Web Api", Version = "v1" });
});

2.4 启用Swagger中间件

  • 在​​Startup.cs​​​文件中的​​Configure​​类中启用Swagger中间件,为生成的 JSON 文档和SwaggerUI 提供服务

//启用Swagger中间件
app.UseSwagger();
//配置SwaggerUI
app.UseSwaggerUI(u =>
{
u.SwaggerEndpoint("/swagger/v1/swagger.json", "WebAPI_v1");
});

2.5 运行项目

  • 2.5.1 如果我们直接运行项目,会出现这样的界面,说明我们的Web API程序没有问题。
  • 然后我们在地址栏中输入​​swagger/v1/swagger.json​
  • 可以看到浏览器出现这样的界面,如果出现这样的界面,说明Swagger也没有问题

    注意:按照2.5.1在地址栏中的​​swagger/v1/swagger.json​​​需要与在​​Startup.cs​​文件中的【Configure】类中启用Swagger中间件添加的代码保持一致,因为这段代码就是自动生成 JSON 文件的,你配置的路径和 JSON 文件地址是什么,就在浏览器中输入对应的即可
  • 以上步骤都没问题的话,然后我们地址栏中输入​​swagger/index.html​
  • 这是Swagger的首页,如果能出现以下界面,说明SwaggerUI也没有问题,都全部正常了

2.6 如果想每次运行都默认直接到Swagger的页面

  • 打开​​launchSettings.json​​这个文件
  • 然后将​​launchUrl​​​的值从​​weatherforecast​​​修改成​​swagger​
  • 修改变成以下代码
  • 然后运行项目就直接进入Swagger首页了

2.7 描述信息详细讲解

在.NET Core Web API 中应用 Swagger_经验分享_03


在.NET Core Web API 中应用 Swagger_api_04

三、启用XML注释

3.1 双击解决方案

在.NET Core Web API 中应用 Swagger_swagger_05

3-2 然后进入这个页面,加上这个代码

在.NET Core Web API 中应用 Swagger_swagger_06

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>

3-3 在​​Startup.cs​​​文件中的​​ConfigureService​​类中注册读取XML信息的Swagger

#region 读取xml信息
// 使用反射获取xml文件,并构造出文件的路径
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 启用xml注释,该方法第二个参数启用控制器的注释,默认为false.
u.IncludeXmlComments(xmlPath, true);
#endregion

在.NET Core Web API 中应用 Swagger_api_07


注意:

  • 对于Linux或者非Windows操作系统,文件名和路径区分大小写。例如:​​MyWebApiUseSwagger.xml​​文件在Windows上有效,但在CentOS上是无效的
  • 获取应用程序路径,建议采用​​Path.GetDirectoryName(typeof(Program).Assembly.Location)​​​这种方式或者​​AppContext.BaseDirectory​​这样来获取

四、实例

4.1 写一个实例:在​​WeatherForecastController​​控制器中写一个方法

在.NET Core Web API 中应用 Swagger_API_08

4.2 写上以下代码然后开始请求

/// <summary>
/// 这是一个例子
/// </summary>
/// <remarks>
/// 描述:这是一个带参数的GET请求
/// Web API
/// </remarks>
/// <param name="id">主键ID</param>
/// <returns>测试字符串</returns>
[HttpGet("{id}")]
public ActionResult<string> Get(int id)
{
return $"你请求的ID是:{id}";
}

4.3 可以看到 XML注释 起作用了,然后调用也成功了

在.NET Core Web API 中应用 Swagger_api_09

五 .Net Core3.1 swagger 文档添加 不用 xml 配置

四中使用 特性的方式来自动生成 swagger 文档的方式,简述的较为笼统,如果没明白请转到博客:​​.Net Core3.1 swagger 文档添加 不用xml配置​​


举报

相关推荐

0 条评论