一、为什么使用Swagger

上文中已经说到，单纯的项目接口在前后端开发人员使用是特别不舒服的，那所有要推荐一个，既方便又美观的接口文档说明框架，当当当，就是Swagger，随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。

前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。

没有API文档工具之前，大家都是手写API文档的，在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。

书写API文档的工具有很多，但是能称之为“框架”的，估计也只有swagger了。

二、配置Swagger服务

1、引用Nuget包

下面开始引入swagger插件

方法有两个：

1）可以去swagger官网或github上下载源码，然后将源码（一个类库）引入自己的项目；

2）直接利用NuGet包添加程序集应用（这里就是前边说的在以后的开发中，Nuget无处不在）。

右键项目中的 Dependencies -- > Manage Nuget Packags --> Browse --> Search "Swashbuckle.AspNetCore" --> Install 5.0以上版本

这里注意下，要勾选上包含预览版，如果不勾选，只能看到4.0版本，毕竟5.0还没有正式发布。

然后就在项目的Nuget依赖包 Packages 里看到刚刚引入的Swagger包

这个时候，你可以试运行一下，当然是不可以的，因为我们还没有配置。

2、配置服务

打开Startup.cs类，编辑 ConfigureServices 类

 public string ApiName { get; set; } = "Blog.Core";  var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;   services.AddSwaggerGen(c => {   c.SwaggerDoc("V1", new OpenApiInfo    {   // {ApiName} 定义成全局变量，方便修改    Version = "V1",  Title = $"{ApiName} 接口文档——Netcore 3.0",  Description = $"{ApiName} HTTP API V1",  Contact = new OpenApiContact { Name = ApiName, Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }, License = new OpenApiLicense { Name = ApiName, Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }   }); c.OrderActionsBy(o => o.RelativePath);  });

3、启动Http中间件

编辑Configure类

 // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.   public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {   if (env.IsDevelopment())    {   app.UseDeveloperExceptionPage();    }   app.UseSwagger();   app.UseSwaggerUI(c =>   {   c.SwaggerEndpoint($"/swagger/V1/swagger.json", $"{ApiName} V1");    //路径配置，设置为空，表示直接在根域名（localhost:8001）访问该文件,注意localhost:8001/swagger是访问不到的，去launchSettings.json把launchUrl去掉，如果你想换一个路径，直接写名字即可，比如直接写c.RoutePrefix = "doc";  c.RoutePrefix = "";  }); app.UseRouting();   app.UseAuthorization(); app.UseEndpoints(endpoints =>   {   endpoints.MapControllers(); }); }

4、查看效果

到这，已经完成swagger的添加，F5 运行调试，因为我们在上边配置swagger中间件的时候，把启动地址设置了空，就是这里

所以这个时候，我们是直接访问域名根目录就行了，比如 localhost://8081即可。

还有一个小问题就是，因为我们的项目，官方默认的是 /WeatherForecast地址，所以我们需要修改一下，在 launchSettings.json 文件中的 launchUrl设置为空，或者删掉就行。

这个时候我们直接访问项目根目录，当当当出来了：

5、好像少点儿什么？！

在上边的截图中，我们可以看到，已经生成了一个 api 列表，我们不仅可以清晰的看到项目中含有那些接口，还可以直接点击发送请求，类似 postman 那样，做接口调试，

但是现在有两个问题：

1、这个接口文档现在还不多，如果多了的话，每个接口对应的意义可能会混淆，

2、另外，这个接口文档，也是方便前端工程师查看的，目前这个这个样式，看起来是挺费解的。

这个时候，要是有一个注释功能就很好了，别着急，看看下边的截图，是不是你想要的效果？！

既美观又快捷，而且还有丰富的注释，这样以后发布出去，前后端开发人员就可以一起开发了，嗯！不错！

那这个注释功能，应该这么做呢？别着急马上开始。

三、swagger文档完善

1、为接口添加注释

接下来，我们就需要解决第二个问题，如何增加文字说明，就是传说中的注释：

右键项目名称=>属性=>生成，勾选“输出”下面的“xml文档文件”，系统会默认生成一个，当然老规矩，你也可以自己起一个名字：

这里我用的是相对路径，可以直接生成到 api 层的 bin文件夹下

这个时候，先别忙着运行项目，作为老司机的我，只要是改代码或者配置文件，保存后，第一件事就是看看有没有错误，一看，咦~~~果然，虽然是警告，可以强迫症呀，一看还挺多

别慌！一看，哦！原来是swagger把一些接口方法都通过xml文件配置了，就是刚刚上文提到的，所以我们只需要加上方法注释就可以辣，可以左斜杠/，连续三下即可

如果你不想每一个方法都这么加注释，可以这么配置（对当前项目进行配置，可以忽略警告，记得在后边加上分号 ;1591）：

现在呢，配置好了xml文件，接下来需要让系统启动的时候，去读取这个文件了，重新编辑Startup.cs，修改ConfigureServices函数：

 var basePath = Microsoft.DotNet.PlatformAbstractions.ApplicationEnvironment.ApplicationBasePath;   services.AddSwaggerGen(c => {   c.SwaggerDoc("V1", new OpenApiInfo    {   // {ApiName} 定义成全局变量，方便修改    Version = "V1",  Title = $"{ApiName} 接口文档——Netcore 3.0",  Description = $"{ApiName} HTTP API V1",  Contact = new OpenApiContact { Name = ApiName, Email = "Blog.Core@xxx.com", Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }, License = new OpenApiLicense { Name = ApiName, Url = new Uri("https://www.jianshu.com/u/94102b59cc2a") }   }); c.OrderActionsBy(o => o.RelativePath);  //就是这里！！！！！！！！！  var xmlPath = Path.Combine(basePath, "blog.core.test3.0.xml");//这个就是刚刚配置的xml文件名  c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改    });

然后F5 运行，都加上了，感觉前端大佬再也不会说看不懂接口了，哈哈哈哈

3、对 Model 也添加注释说明

接下来开始第三个问题：添加实体类说明注释：

新建一个.net core 类库Blog.Core.Model，注意是 .net core的类库，或者使用标准库也是可以的！（标准库可以在 NetCore 和 Framework 两个项目都可以跑）

新建一个Love的实体类

    /// <summary> /// 这是爱 /// </summary>    public class Love   {   /// <summary> /// id  /// </summary>    public int Id { get; set; } /// <summary> /// 姓名  /// </summary>    public string Name { get; set; }    /// <summary> /// 年龄  /// </summary>    public int Age { get; set; }    }

这里现在有两个情况，或者说是两个操作方案：

1、当前 api 层直接引用了 Blog.Core.Model 层；

这个时候，我们只需要配置仿照上边 api 层配置的xml文档那样，在 Blog.Core.Model 层的 XML 输出到 API 层就行了：

2、API 层没有直接引用 Model 层，而是通过级联的形式；

就比如我的 Github 上的代码那样：

效果和上边是一样的，也算是引用 Model 层了。

4、改写注入方法，并在控制器中参数引用

配置xml文档，在 startup.cs 的 configureService 方法里

    //就是这里  var xmlPath = Path.Combine(basePath, "Blog.Core.xml");//这个就是刚刚配置的xml文件名  c.IncludeXmlComments(xmlPath, true);//默认的第二个参数是false，这个是controller的注释，记得修改    var xmlModelPath = Path.Combine(basePath, "Blog.Core.Model.xml");//这个就是Model层的xml文件名 c.IncludeXmlComments(xmlModelPath);

接口添加注释

  　　　/// <summary>    /// post    /// </summary>    /// <param name="love">model实体类参数</param>    [HttpPost]  public void Post(Love love) {   }

dang dang dang，就出来了

5、去掉Swagger警告提示

在Model层中，我们建立了很多实体，如果你没有为每一个实体都添加注释的话，可能会出现这样的警告：

如果有的小伙伴，不想添加注释，而又不想看到这个强迫症的警告提示，那就可以这么做，

右键项目属性 -》 Errors and warnings 配置 1591：

6、隐藏某些接口

如果不想显示某些接口，直接在controller 上，或者action 上，增加特性

[ApiExplorerSettings(IgnoreApi = true)]

或者直接对这个方法 private，也可以直接使用obsolete属性

四、Github && Gitee

https://github.com/anjoy8/Blog.Core.git

https://gitee.com/laozhangIsPhi/Blog.Core

【 .NET Core 3.0 】框架之三 || swagger的使用相关推荐

asp.net core 3.0 中使用 swagger
asp.net core 3.0 中使用 swagger Intro 上次更新了 asp.net core 3.0 简单的记录了一下 swagger 的使用,那个项目的 api 比较简单,都是匿名接口 ...
.NET Core 3.0 webapi集成Swagger 5.0
在项目中引用Swashbuckle.AspNetCore和Swashbuckle.AspNetCore.Filters两个dll,在Startup中的ConfigureServices相关配置代码如下 ...
ASP.NET Core 2.0 特性介绍和使用指南
ASP.NET Core 2.0 发布日期:2017年8月14日 ASP.NET团队宣布ASP.NET Core 2.0正式发布,发布Visual Studio 2017 15.3支持ASP.NET ...
NET Core 3.0 项目中使用 AutoFac
.net core 3.1 今天已正式发布,3.1跟3.0差别不是很大,主要是对 3.0一小部分修复和完善,最重要的是.NET Core 3.1是长期支持(LTS)版本,建议大家升级. .net co ...
使用gRPC的.NET Core 3.0双向消息流
目录介绍软件描述服务器基础结构(GrpcServerHelper) 客户基础设施(GrpcClientHelper) GrpcServer和GrpcClient 运行示例结论下载源码 - 2 ...
向net core 3.0进击——Swagger的改变
前言十一小长假在不知不觉间可都没了,在这个小尾巴的空隙,把这两天鼓捣的net core 3.0升级过程记录一下,首先还是根据之前的顺序一个个补充进来,先从Swagger的变化说起(新建工程什么的不多 ...
Core 3.0使用Swagger＜完全图解＞
Core 3.0使用Swagger 完全图解教程----系列1 什么是Swagger Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件.Swagger是一个规范和完整的框架, ...
ASP.NET CORE 1.0 MVC API 文档用 SWASHBUCKLE SWAGGER实现
from:https://damienbod.com/2015/12/13/asp-net-5-mvc-6-api-documentation-using-swagger/ 代码生成工具: https ...
【转载】从头编写 asp.net core 2.0 web api 基础框架 (1)
工具: 1.Visual Studio 2017 V15.3.5+ 2.Postman (Chrome的App) 3.Chrome (最好是) 关于.net core或者.net core 2.0的相 ...

【 .NET Core 3.0 】框架之三 || swagger的使用