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

我们为什么选择swagger,现在的网站开发结果越来越注重前后端的分离,比如以前的webFrom到现在的mvc模式都是为了这个前后端的分离。就算再如何的分离实现,也是不可避免的要进行数据交互的,那么接口的重要性就提现出来了。他成了前端和后端交互的重要途径,API文档也因此成了前端开发人员与后端开发人员的重要纽带。所有我们有一个API文档框架岂不是美哉。

Swashbuckle有三个主要组件:

Swashbuckle.AspNetCore.Swagger:Swagger对象模型和中间件,将SwaggerDocument对象公开为JSON端点。
Swashbuckle.AspNetCore.SwaggerGen:一种Swagger生成器,可SwaggerDocument直接从路由,控制器和模型构建对象。它通常与Swagger端点中间件结合使用,以自动公开Swagger JSON。
Swashbuckle.AspNetCore.SwaggerUI:Swagger UI工具的嵌入式版本。它将Swagger JSON解释为构建丰富的,可定制的Web API功能描述体验。它包括用于公共方法的内置测试线束。

如何使用vs2019安装Swashbuckle

从“管理 NuGet 程序包”对话框中或“程序包管理器控制台”窗口进行安装。

从“程序包管理器控制台”窗口进行安装:

  • 转到“视图” > “其他窗口” > “程序包管理器控制台”
  • 将“默认项目”改为需要添加的项目。
  • 输入命令 ·Install-Package Swashbuckle.AspNetCore

从“管理 NuGet 程序包”对话框中:

  • 右键单击“解决方案资源管理器” > “管理 NuGet 包”中的项目
  • 将“包源”设置为“nuget.org”
  • 在搜索框中输入“Swashbuckle.AspNetCore”
  • 从“浏览”选项卡中选择“Swashbuckle.AspNetCore”包,然后单击“安装”

如果你看到这段文字,说明您正使用RSS阅读或转自《一棵树-博客园》,原文地址:https://www.cnblogs.com/atree/p/netcore-WebApi-Swagger.html

添加并配置Swagger中间件

然后配置Startup.cs 文件中的ConfigureServices方法。

//不要忘记引用一下using Swashbuckle.AspNetCore.Swagger命名空间,不然info类会报错
using Swashbuckle.AspNetCore.Swagger
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc()
.SetCompatibilityVersion (CompatibilityVersion.Version_2_1)
.AddJsonOptions (options =>
options.SerializerSettings.ContractResolver =
new Newtonsoft.Json.Serialization.DefaultContractResolver ()); //JSON首字母小写解决; //注册Swagger生成器,定义一个和多个Swagger 文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc ("v1", new Info { Title = "My API", Version = "v1" });
});
}

然后在Configure方法中添加:

//允许中间件为JSON端点服务生成的Siggg
app.UseSwagger ();
//使中间件能够服务于轻量级用户界面(HTML、JS、CSS等),并指定SWAGJER JSON端点
app.UseSwaggerUI (c => {
c.SwaggerEndpoint ("/swagger/v1/swagger.json", "My API V1");
// 要在应用程序的根处提供Swagger UI ,请将该RoutePrefix属性设置为空字符串
c.RoutePrefix = string.Empty;
});

启动应用,并导航到 http://localhost:<port>/swagger/v1/swagger.json。 生成的描述终结点的文档显示如下json格式。

可在 http://localhost:<port>/swagger 找到 Swagger UI。也可设置其他地址,我把他配置成了根节点,这样直接启动根节点就是该页面。主要是上面代码中的: c.RoutePrefix = string.Empty这句代码。

我们可以扩展一些附加信息,比如作者,许可证,服务条款等。传递给该AddSwaggerGen方法的配置:

//Swagger生成器添加到方法中的服务集合中
services.AddSwaggerGen (options => {
options.SwaggerDoc ("v1", new Info {
Version = "v1",
Title = " API 文档",
Description = "这是一个示例webapi文档",
//服务条款
TermsOfService = "None Services",
//作者信息
Contact = new Contact {
Name = "atree",
Email = string.Empty,
Url = "https://www.cnblogs.com/atree/"
},
//许可证
License = new License {
Name = "许可证名字",
Url = "http://www.cnblogs.com/atree/"
}
}); });

为接口增加注释

启用XML注释可为未记录的公共类型和成员提供调试信息。未记录的类型和成员由警告消息指示。配置Swagger以使用生成的XML文件。

在我们实现前先设置一下项目属性:

这样就可以在项目bin下生成xml文件了。下面进行代码配置启用,还是在Startup类中的ConfigureServices方法中,在我们刚才配置的下面在增加以下代码:

// 设置SWAGER JSON和UI的注释路径。
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine (AppContext.BaseDirectory, xmlFile);
options.IncludeXmlComments (xmlPath);

使用反射主要是为了生成一个与项目文件名相同的xml文件。第二部然后是配置文件路径。这些配置好了以后。我们就可以把方法或者类的三道斜杠(“///”)的注释添加到动作。我们来看一下效果。

好了,这样在.NET Core WebApi项目中,使用Swagger生成api说明文档已经完成了。如果需要对外展示,还可以修改UI界面,还没有试过。对内部用,这样就可以了。

.NET Core WebApi帮助文档使用Swagger生成Api说明文档的更多相关文章

  1. NetCore 3.0 中使用Swagger生成Api说明文档及升级报错原因

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

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

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

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

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

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

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

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

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

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

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

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

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

  8. ASP.NET Core WebApi使用Swagger生成API说明文档【xml注释版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

  9. ASP.NET Core WebApi使用Swagger生成API说明文档【特性版】

    ⒈新建ASP.NET Core WebAPi项目 ⒉添加 NuGet 包 Install-Package Swashbuckle.AspNetCore ⒊Startup中配置 using System ...

随机推荐

  1. Entity Framework 6 中如何获取 EntityTypeConfiguration 的 Edm 信息?(二)

    接着上一篇 直接贴代码了: using System; using System.Collections.Generic; using System.Data.Entity; using System ...

  2. virsh 查看信息

    获取域网络接口信息 virsh domiflist debian8 获取vcpu信息 virsh vcpuinfo debian8 设定内存最大内存 virsh setmaxmem debian8 9 ...

  3. php 5.5 编译安装

    链接:https://pan.baidu.com/s/1Iy5kdugWqmvtsrYG0WYAdA 提取码:knk9 上面的链接 php5.5.8 编译安装的包 ./configure  --pre ...

  4. 【机器学习笔记】Python机器学习基本语法

    本来算法没有那么复杂,但如果因为语法而攻不下就很耽误时间.于是就整理一下,搞python机器学习上都需要些什么基本语法,够用就行,可能会持续更新. Python四大类型 元组tuple,目前还没有感受 ...

  5. WEB网站发布服务器IIS报错问题终极解决方案,查到问题点

    4本次错误webservice发布新服务器后,出现此错误. 解决方法: 找到dmp文件 dmp文件是啥?自己百度.简单的说就是黑匣子,记录程序崩溃前的操作,那么如何找到这个黑匣子呢? 1.启动 Win ...

  6. Python【day 11】函数名的应用

    函数名的应用 1.函数名字可以作为参数进行传递 2.函数名可以像变量一样进行多次赋值传递,通过print(函数名.__name__)查看原函数 3.函数名表示函数的内存地址 4.函数名()表示函数的执 ...

  7. android studio学习----常用快捷键

    Action Mac OSX Win/Linux 注释代码(//) Cmd + / Ctrl + / 注释代码(/**/) Cmd + Option + / Ctrl + Shift + / 格式化代 ...

  8. Fundebug录屏插件更新至0.5.0,新增domain参数

    摘要: 通过配置domain来保证"视频"的正确录制 录屏功能介绍 Fundebug提供专业的异常监控服务,当线上应用出现 BUG 的时候,我们可以第一时间报警,帮助开发者及时发现 ...

  9. Transformer —— attention is all you need

    https://www.cnblogs.com/rucwxb/p/10277217.html Transformer -- attention is all you need Transformer模 ...

  10. Pyqt5开发一款小工具(翻译小助手)

    翻译小助手 开发需求 首先五月份的时候,正在学习爬虫的中级阶段,这时候肯定要接触到js逆向工程,于是上网找了一个项目来练练手,这时碰巧有如何进行对百度翻译的API破解思路,仿造网上的思路,我摸索着完成 ...