网站建设网站推广,芜湖效能建设网站,盘州网站建设,用vs做音乐网站前言随着前后端分离开发模式的流行#xff0c;接口对接、联调成为常事#xff0c;前端同事会经常问#xff1a;我需要调哪个接口#xff1f;这个接口数据格式是啥#xff1f;条件都传啥#xff1f; 对于一些紧急接口可能会采取沟通对接#xff0c;然后补文档#xff0c… 前言随着前后端分离开发模式的流行接口对接、联调成为常事前端同事会经常问我需要调哪个接口这个接口数据格式是啥条件都传啥 对于一些紧急接口可能会采取沟通对接然后补文档其他的都会回一句看文档。 那难道要一边开发一边写文档吗早些年是这样的但对于后端同事就很不自在了代码敲的正起劲突然又要去写文档(不然前端同事会时刻催或是来沟通)这样效率显然不是很高。而Swagger就能很舒服的解决问题(当然也有其他方式挑一个比较火的)用Swagger大概会有以下好处良好的可视化界面在线查看即可(可自定义)前后端对接方便避免边撸代码边写文档可以直接进行API运行提高自测效率文档生成方便结合第三方API接口管理平台(YApi等)轻松生成文档(软件文件备案需要好多文档的)。不写文档更多时间撸代码~~~正文直接上案例演示老规矩还是熟悉的WebApi项目运行演示如果注册组件时设置的名称和注册中间件时设置的json地址中的名称不一样就会报以下错误轻松三步走完成Swagger的集成安装包-注册组件-注册中间件但是运行起来的时候还需要手动输入Url地址不太友好希望运行起来就直接是Swagger的页面如下优化一下代码这样就完事了吗 当然没有这样前端同事还得时刻找你问我要用哪个接口接口参数的字段都是啥意思因为接口列表虽然展示出来了但是不知道接口功能传入的条件参数字段分别代表什么意思。来加个注释解决烦恼新加的用户接口已经自动列出来了但是我们在代码中已经注释Swagger界面还是没有显示那是因为还没有指定Swagger的注释来源呢。这里先注意一个问题如果Action不显示指定HttpMethod(如HttpGet、HttpPost等)Swagger会报错如下来我们的注释还没显示出来呢继续往下看看↓↓↓先针对API项目和Model项目配置生成项目对应的xml文件增加代码分别指定配置文件解析注释然后运行演示这样就已经完成在Swagger在线文档中添加文字说明了解决前后端对接的麻烦事。但是在编译运行的时候会出现很多警告提示没有注释(CS1591)这是因为生成xml文件要求都需要注释导致作为程序员的洁癖当然不允许这种情况发生小红框标识提示代码为1591我们在项目右键-属性-生成界面中增加该代码即可如下再编译运行一下是不是警告没了整洁就是舒服~~~~~这里有个小细节在配置xml读取注释时如果不使用第二个参数默认控制器的注释是不管用的这里就不运行演示了代码说明如下Swagger的集成使用差不多了后续会在认证的时候做扩展。对于Swagger的页面开发已经是绝对能满足了但总有一些审美比较严格或是有一些页面定制化的需求所以自定义页面就避免不了小伙伴会发现项目中只是安装了Swagger的包没有对应的静态文件那是怎么访问的呢嗖的一下灵光一闪小伙伴一定想到之前文件系统中说到的嵌入文件(编译到程序集中的文件)默认情况下Swagger的相关文件都是嵌入文件所以在项目中看不到。自定义页面有三种方式Swagger的页面是前后端分离的可直接下载下来扩展直接写一个主页页面然后注入相关JS最后将其改为嵌入文件显示指定加载页面通过Swagger默认提供的API注入相关的Js文件进行页面自定义相对来说第一种比较清晰而且代码与后端代码没有啥关系所以这里就以第一种为例进行演示其余两种留给小伙伴探索探索。大概步骤先下载Swagger前后端项目文件(下载地址:https://github.com/swagger-api/swagger-ui/)将下载下来的dist中文件拷贝到WebApi中的wwwroot目录WebApi开启静态文件处理能力即注册静态文件中间件修改静态文件(文件在本地想怎么搞就怎么搞)运行看效果这里只是提供思路样式不好看别说我(小伙伴不会说对不对)美化只是时间问题嘛自定义界面就是这么简单。补充两个小技巧通常有一些接口已经过时但有不能马上废弃可以给一个提示加[Obsolete]特性代表其已经废弃但还可以用有一个替换的过渡期。有时候有些接口不想显示在Swagger文档中可以加[ApiExplorerSettings(IgnoreApi true)]总结看到这篇小伙伴可能会好奇这么简单的集成为什么要长篇大论的说那么多。其实我是站在我之前学习的角度想让每个用法都清楚的表达出来在使用的时候也知道为什么会这样所以后续的文章会循序渐进不会一下跳到Docker部署网关使用之类的主题如果没有学过Docker看着文档也很懵就算照着案例做出来收获也不是很大别急该说的都会一一到来同时我也会不断学习争取分享更多技术知识。下一节说说Jwt认证集成使用。一个被程序搞丑的帅小伙关注Code综艺圈识别关注跟我一起学~~~撸文不易莫要白瞟三连走起~~~~
