跟我一起学.NetCore之Swagger让前后端不再烦恼及界面自定义

来源: 跟我一起学.NetCore之Swagger让前后端不再烦恼及界面自定义

前言

随着前后端分离开发模式的流行,接口对接、联调成为常事,前端同事会经常问:我需要调哪个接口?这个接口数据格式是啥?条件都传啥? 对于一些紧急接口可能会采取沟通对接,然后补文档,其他的都会回一句:看文档。 那难道要一边开发一边写文档吗?早些年是这样的,但对于后端同事就很不自在了,代码敲的正起劲,突然又要去写文档(不然前端同事会时刻催或是来沟通),这样效率显然不是很高。而Swagger就能很舒服的解决问题(当然也有其他方式,挑一个比较火的),用Swagger大概会有以下好处:

  • 良好的可视化界面,在线查看即可(可自定义);
  • 前后端对接方便,避免边撸代码边写文档;
  • 可以直接进行API运行,提高自测效率;
  • 文档生成方便,结合第三方API接口管理平台(YApi等)轻松生成文档(软件文件备案需要好多文档的)。不写文档,更多时间撸代码~~~

正文

直接上案例演示,老规矩,还是熟悉的WebApi项目:

运行演示:

如果注册组件时设置的名称和注册中间件时设置的json地址中的名称不一样,就会报以下错误:

轻松三步走完成Swagger的集成:安装包->注册组件->注册中间件;

但是运行起来的时候还需要手动输入Url地址,不太友好,希望运行起来就直接是Swagger的页面,如下优化一下代码:

这样就完事了吗? 当然没有,这样前端同事还得时刻找你问:我要用哪个接口?接口参数的字段都是啥意思?因为接口列表虽然展示出来了,但是不知道接口功能,传入的条件参数字段分别代表什么意思。

来,加个注释解决烦恼:

新加的用户接口已经自动列出来了,但是我们在代码中已经注释,Swagger界面还是没有显示,那是因为还没有指定Swagger的注释来源呢。这里先注意一个问题,如果Action不显示指定HttpMethod(如:HttpGet、HttpPost等),Swagger会报错,如下:

来,我们的注释还没显示出来呢,继续往下看看↓↓↓

  1. 先针对API项目和Model项目配置生成项目对应的xml文件;

  2. 增加代码,分别指定配置文件解析注释,然后运行演示;

这样就已经完成在Swagger在线文档中添加文字说明了,解决前后端对接的麻烦事。但是在编译运行的时候,会出现很多警告,提示没有注释(CS1591):

这是因为生成xml文件要求都需要注释导致,作为程序员的洁癖,当然不允许这种情况发生,小红框标识提示代码为1591,我们在项目右键->属性->生成界面中增加该代码即可,如下:

再编译运行一下,是不是警告没了,整洁就是舒服~~~~~

这里有个小细节,在配置xml读取注释时,如果不使用第二个参数,默认控制器的注释是不管用的,这里就不运行演示了,代码说明如下:

Swagger的集成使用差不多了,后续会在认证的时候做扩展。

对于Swagger的页面,开发已经是绝对能满足了,但总有一些审美比较严格,或是有一些页面定制化的需求,所以自定义页面就避免不了;小伙伴会发现,项目中只是安装了Swagger的包,没有对应的静态文件,那是怎么访问的呢?嗖的一下,灵光一闪,小伙伴一定想到之前文件系统中说到的嵌入文件(编译到程序集中的文件),默认情况下,Swagger的相关文件都是嵌入文件,所以在项目中看不到。自定义页面有三种方式:

  • Swagger的页面是前后端分离的,可直接下载下来扩展;
  • 直接写一个主页页面,然后注入相关JS,最后将其改为嵌入文件,显示指定加载页面;
  • 通过Swagger默认提供的API,注入相关的Js文件进行页面自定义;

相对来说,第一种比较清晰,而且代码与后端代码没有啥关系,所以这里就以第一种为例进行演示,其余两种留给小伙伴探索探索。

大概步骤:

  1. 先下载Swagger前后端项目文件(下载地址:https://github.com/swagger-api/swagger-ui/);
  2. 将下载下来的dist中文件拷贝到WebApi中的wwwroot目录;

  3. WebApi开启静态文件处理能力,即注册静态文件中间件;

  4. 修改静态文件(文件在本地,想怎么搞就怎么搞);

  5. 运行看效果:

这里只是提供思路,样式不好看别说我(小伙伴不会说,对不对),美化只是时间问题嘛,自定义界面就是这么简单。

补充两个小技巧:

  • 通常有一些接口已经过时,但有不能马上废弃,可以给一个提示;加[Obsolete]特性代表其已经废弃,但还可以用,有一个替换的过渡期。
  • 有时候有些接口不想显示在Swagger文档中,可以加[ApiExplorerSettings(IgnoreApi = true)]

总结

看到这篇小伙伴可能会好奇,这么简单的集成,为什么要长篇大论的说那么多。其实我是站在我之前学习的角度,想让每个用法都清楚的表达出来,在使用的时候也知道为什么会这样,所以后续的文章会循序渐进,不会一下跳到Docker部署,网关使用之类的主题,如果没有学过Docker,看着文档也很懵,就算照着案例做出来,收获也不是很大;别急,该说的都会一一到来,同时我也会不断学习,争取分享更多技术知识。下一节说说Jwt认证集成使用。

赞(0) 打赏
分享到: 更多 (0)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏