认识Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
作用:

    1. 接口的文档在线自动生成。
    2. 功能测试。

为什么使用Swagger作为REST APIs文档生成工具

  1. Swagger 可以生成一个具有互动性的API控制台,开发者可以用来快速学习和尝试API。
  2. Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
  3. Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
  4. Swagger 有一个强大的社区,里面有许多强悍的贡献者。

安装Nuget包搜索Swashbuckle.AspNetCore

因为是.NetCore3.0 ,所以一定要勾选包括预览发行版,安装最新预发行版 5.0.0-rc4,千万不要安装最新稳定版。稳定版会报错。
稳定版报错信息:

 Some services are not able to be constructed (Error while validating the service descriptor 'ServiceType:
Swashbuckle.AspNetCore.Swagger.ISwaggerProvider Lifetime: Transient ImplementationType:
Swashbuckle.AspNetCore.SwaggerGen.SwaggerGenerator': Failed to compare two elements in the array.)
(Error while validating the service descriptor 'ServiceType: Swashbuckle.AspNetCore.SwaggerGen.ISchemaRegistryFactory Lifetime:
Transient ImplementationType: Swashbuckle.AspNetCore.SwaggerGen.SchemaRegistryFactory': Failed to compare two elements in the array.)

解决办法就是3.0版本中要安装现在预览发行版5.0.0-rc4

在.NetCore3.0中 配置Swagger 也发生变化,
由以前的

 services.AddSwaggerGen(c =>
{
  c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

变更为

 services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

其中最大的变化就是Info这里,在以前2.0版本中是由Swagger来管理的。在3.0版本中统一变更为 OpenApi管理,OpenApi 在官方文档中介绍为是用于管理项目内 OpenAPI 引用的 .NET Core 全局工具。

参考地址:(https://docs.microsoft.com/zh-cn/aspnet/core/web-api/microsoft.dotnet-openapi?view=aspnetcore-3.1 "使用 OpenAPI 工具开发 ASP.NET Core 应用")

所以在添加完Swagger 包后,还要在项目中添加Microsoft.OpenApi包

注册Swagger

 public void ConfigureServices(IServiceCollection services)
{ services.AddControllers(); services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
}); }

配置Swagger UI

 public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
//启用Swagger
app.UseSwagger();
//配置Swagger UI
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API"); //注意中间段v1要和上面SwaggerDoc定义的名字保持一致
});
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}

启动项目

CTRL+F5启动项目,并导航到 http://localhost:port/swagger 通过Swagger UI游览API文档

Swagger的高级用法(自定义扩展)

在 AddSwaggerGen 方法的进行如下的配置操作会添加诸如作者、许可证和说明信息等:

 services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "My API",
Version = "v1",
Description = "API文档描述",
Contact = new OpenApiContact
{
Email = "8596007@qq.com",
Name = "开源NetCore",
Url = new Uri("http://www.netcore.pub/")
},
License = new OpenApiLicense
{
Name = "许可证名称",
Url = new Uri("http://www.netcore.pub/")
}
});
});

Swagger UI 显示版本的信息如下图所示

为API接口方法添加注释

大家先点开API,展开如下图所示,可是没有注释呀,怎么添加注释呢?

按照下列代码所示用三个/添加文档注释,如下所示

 /// <summary>
/// 这是一个API注释
/// </summary>
/// <returns></returns>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
var rng = new Random();
return Enumerable.Range(, ).Select(index => new WeatherForecast
{
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-, ),
Summary = Summaries[rng.Next(Summaries.Length)]
})
.ToArray();
}

然后运行项目,回到Swagger UI中去查看注释是否出现了呢

还是没出现?一脸懵逼??? 别急往下看!

启用XML注释

可使用以下方法启用 XML 注释:

右键单击“解决方案资源管理器”中的项目,然后选择“属性”
查看“生成”选项卡的“输出”部分下的“XML 文档文件”框

启用 XML 注释后会为未记录的公共类型和成员提供调试信息。如果出现很多警告信息 例如,以下消息指示违反警告代码 1591:

 warning CS1591: Missing XML comment for publicly visible type or member 'TodoController.GetAll()'

如果你有强迫症,想取消警告怎么办呢?可以按照下图所示进行取消

注意上面生成的xml文档文件的路径,

注意:

​ 1.对于 Linux 或非 Windows 操作系统,文件名和路径区分大小写。 例如,“Kylin.Wiki.xml”文件在 Windows 上有效,但在 CentOS 上无效。

​ 2.获取应用程序路径,建议采用Path.GetDirectoryName(typeof(Program).Assembly.Location)这种方式或者·AppContext.BaseDirectory这样来获取

 services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo
{
Title = "My API",
Version = "v1",
Description = "API文档描述",
Contact = new OpenApiContact
{
Email = "8596007@qq.com",
Name = "开源NetCore",
Url = new Uri("http://www.netcore.pub/")
},
License = new OpenApiLicense
{
Name = "许可证名称",
Url = new Uri("http://www.netcore.pub/")
}
});
// 为 Swagger JSON and UI设置xml文档注释路径
var basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);//获取应用程序所在目录(绝对,不受工作目录影响,建议采用此方法获取路径)
var xmlPath = Path.Combine(basePath, "Kylin.Wiki.xml");
c.IncludeXmlComments(xmlPath);
});

重新生成并运行项目查看一下注释出现了没有

通过上面的操作可以总结出,Swagger UI 显示上述注释代码的元素的内部文本作为api大的注释!

当然你还可以将 remarks 元素添加到 Get 操作方法文档。 它可以补充元素中指定的信息,并提供更可靠的 Swagger UI。 元素内容可包含文本、JSON 或 XML。 代码如下:

 /// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
public ActionResult<string> Get(int id)
{
return $"你请求的 id 是 {id}";
}

重新生成下项目,当好到SwaggerUI看到如下所示:

描述响应类型

接口使用者最关心的就是接口的返回内容和响应类型啦。下面展示一下201和400状态码的一个简单例子:

我们需要在我们的方法上添加:

[ProducesResponseType(201)]

[ProducesResponseType(400)]

然后添加相应的状态说明:返回value字符串如果id为空

最终代码应该是这个样子:

  /// <summary>
/// 这是一个带参数的get请求
/// </summary>
/// <remarks>
/// 例子:
/// Get api/Values/1
/// </remarks>
/// <param name="id">主键</param>
/// <returns>测试字符串</returns>
/// <response code="201">返回value字符串</response>
/// <response code="400">如果id为空</response>
// GET api/values/2
[HttpGet("{id}")]
[ProducesResponseType()]
[ProducesResponseType()]
public ActionResult<string> Get(int id)
{
return $"你请求的 id 是 {id}";
}

效果如下所示
状态相应效果

使用SwaggerUI测试api接口

下面我们通过一个小例子通过SwaggerUI调试下接口吧

点击一个需要测试的API接口,然后点击Parameters左右边的“Try it out ” 按钮
在出现的参数文本框中输入参数,如下图所示的,输入参数2
点击执行按钮,会出现下面所示的格式化后的Response,如下图所示

好了,今天的在ASP.NET Core WebApi 3.0 中使用Swagger生成api说明文档教程就到这里了。希望能够对大家学习在ASP.NET Core中使用Swagger生成api文档有所帮助!

「开源NetCore,如果觉得我的文章对您有用,请帮助本站成长」

除非注明,文章均由开源 NetCore整理发布,欢迎转载。

转载请注明本文地址:http://www.netcore.pub/167.html

站长会将优质文章在各大平台同步更新、推送,欢迎大家访问、订阅:

博客园: https://www.cnblogs.com/Zenderblogs/

NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因的更多相关文章

  1. Web Api 2.0中使用Swagger生成Api文档的2个小Tips

    当Web Api 2.0使用OAuth2授权时,如何在Swagger中添加Authorization请求头? Swagger说明文档支持手动调用Api, 但是当Api使用OAuth2授权时,由于没有地 ...

  2. ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

    参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view ...

  3. ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必是件很痛苦的事情吧,但文档又必须写,而且文档的格式如果没有具体要求的话,最终完成的文档则完全取决于开发者 ...

  4. ASP.NET Core WebApi使用Swagger生成api说明文档

    1. Swagger是什么? Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件 ...

  5. 【转】ASP.NET Core WebApi使用Swagger生成api说明文档看这篇就够了

    原文链接:https://www.cnblogs.com/yilezhu/p/9241261.html 引言 在使用asp.net core 进行api开发完成后,书写api说明文档对于程序员来说想必 ...

  6. .NET Core WebApi帮助文档使用Swagger生成Api说明文档

    Swagger也称为Open API,Swagger从API文档中手动完成工作,并提供一系列用于生成,可视化和维护API文档的解决方案.简单的说就是一款让你更好的书写API文档的框架. 我们为什么选择 ...

  7. Asp.Net Core Web Api 使用 Swagger 生成 api 说明文档

    最近使用 Asp.Net Core Web Api 开发项目服务端.Swagger 是最受欢迎的 REST APIs 文档生成工具之一,进入我的视野.以下为学习应用情况的整理. 一.Swagger 介 ...

  8. 使用swagger生成API说明文档

    使用swagger生成API说明文档本文由个人总结,如需转载使用请标明原著及原文地址没有导出!!!!!不要整天给我留言导出呢,那个是你们百度的时候下面的推荐文章带的关键字,要做导出从swagger取数 ...

  9. 三分钟学会 ASP.NET Core WebApi使用Swagger生成api说明文档

    什么是Swagger?为啥要用Swagger? Swagger可以从不同的代码中,根据注释生成API信息,Swagger拥有强大的社区,并且对于各种语言都支持良好,有很多的工具可以通过swagger生 ...

随机推荐

  1. windows下同时装了Python3和Python2,如何区分使用?

    1.前言 想学习Python3,但是暂时又离不开Python2.在Windows上如何让它们共存呢? 目前国内网站经常会让大家把其中一个python.exe改个名字,这样区分开两个可执行文件的名字,但 ...

  2. web应用安全框架选型:Spring Security与Apache Shiro

    一. SpringSecurity 框架简介 官网:https://projects.spring.io/spring-security/ 源代码: https://github.com/spring ...

  3. GO 基础学习笔记(4)| 参数传递

    Go 语言的命令行参数传递 //通过下面实操可知,通过命令行传递文件和参数 可复制 1 package main 2 3 import( 4 "fmt" 5 "os&qu ...

  4. [LINQ2Dapper]最完整Dapper To Linq框架(四)---Linq和SQL并行使用

    目录 [LINQ2Dapper]最完整Dapper To Linq框架(一)---基础查询 [LINQ2Dapper]最完整Dapper To Linq框架(二)---动态化查询 [LINQ2Dapp ...

  5. day-5元组专区

    *元组,元素不可被修改,不能被增加或者删除tupletu = (11,22,33,44)tu.count(22),获取指定元素在元组中出现的次数tu.index(22),索引22在元组中位置(左到右第 ...

  6. java中的线程安全

    在Java中,线程的安全实际上指的是内存的安全,这是由操作系统决定的. 目前主流的操作系统都是多任务的,即多个进程同时运行.为了保证安全,每个进程只能访问分配给自己的内存空间,而不能访问别的.分配给别 ...

  7. linux命令--文件目录操作命令

    一.命令的基本格式 1.命令提示符 [root@love2 ~]# []:这是提示符的分隔符号,没有特殊含义. root:显示的是当前的登录用户. @:分隔符号,没有特殊含义.love2:当前系统的主 ...

  8. Kafka幂等性原理及实现剖析

    1.概述 最近和一些同学交流的时候反馈说,在面试Kafka时,被问到Kafka组件组成部分.API使用.Consumer和Producer原理及作用等问题都能详细作答.但是,问到一个平时不注意的问题, ...

  9. (三十五)golang--面向对象之多态

    多态:变量具有多种形态,可以用统一的接口来调用不同的实现. 接口体现多态特征: (1)多态参数:之前所讲的Usb接口案例,既可以接受手机变量,也可以接受相机变量,就体现了usb接口的多态: (2)多台 ...

  10. 024.掌握Pod-部署MongoDB

    一 前期准备 1.1 前置条件 集群部署:Kubernetes集群部署参考003--019. glusterfs-Kubernetes部署:参考<附010.Kubernetes永久存储之Glus ...