关于建设信息网站的请示,建站公司跑路了域名怎么办,定制软件开发文案,网站设计开发文档模板下载本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle#xff1b;因为项目需要统一api文档的风格#xff0c;并要支持多种开发语言#xff08;C##xff0c;java#xff0c;python#xff09;#xff0c;所以首先想到的是swagger来构建api文档#xff0c;本章讲解… 本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle因为项目需要统一api文档的风格并要支持多种开发语言C#javapython所以首先想到的是swagger来构建api文档本章讲解的是对.net的webpi来生成文档后续会将java的springmvcswagger来构建接口文档。准备工作快速构建简易api文档swagger文档支持在header中增加Token参数. 准备工作 首先创webapi项目然后通过nuget管理器安装Swashbuckle的包我这里通过console命令安装 Install-Package Swashbuckle -Version 5.6.0 注意只需要安装这个包就行了其他的会自动引用由于Swashbuckle包含了swagger的引用所以不用再单独操作引用了。. 快速构建简易api文档 如上安装完Swashbuckle后其实就能够直接运行看效果了我这里的访问路径是 http://localhost:51847/swagger/ui/index 注意/swagger/ui/index 是默认固定的路径这是nuget包封装的路径访问后能看到如下界面效果 一个简易的文档就弄好了swagger的颜色看起来搭配不错由于大多数接口都是post请求方式因此咋们以/api/values的post接口为例如 对于接口文档而言上面文档存在如下一些疏漏未说明方法的功能参数属性的描述没有返回属性的描述没有 为了方便其他人员对接接口所以对接口文档我们需要增加一些描述要增加描述这里就要知晓Swashbuckle是通过xml文件来读取配置信息的该xml文件里面包含了我们在代码中对方法对类对参数对返回值做的文字描述首先定义一个请求和响应的实体 如/// summary /// 登录请求 /// /summary public class MoLoginRq { /// summary /// 账号 /// /summary public string UserName { get; set; } /// summary /// 密码 /// /summary public string UserPwd { get; set; } } /// summary /// 登录返回 /// /summary public class MoLoginRp { /// summary /// 登录返回的token /// /summary public string Token { get; set; } } 新增一个登录接口代码如/// summary /// 登录接口 /// /summary /// param namerq请求/param /// returns响应/returns [HttpPost] public MoLoginRp Login(MoLoginRq rq) { MoLoginRp rp new MoLoginRp(); rp.Token Guid.NewGuid().ToString(); return rp; } 到这里基本的动作都做完了剩下的是上面我们说的xml文件怎么来又怎么和swagger关联 首先看项目的App_Start文件夹里面应该在安装nuget包的时候会自动增加一个 SwaggerConfig.cs 文件里面就是swagger使用的一些设置我们需要找到被注释的 //c.IncludeXmlComments(GetXmlCommentsPath()); 代码取消注释并创建一个 GetXmlCommentsPath() 方法获取xml注释文件路径 如public static string GetXmlCommentsPath() { //D:/WebApplication/bin/WebApplication.xml return Path.Combine( AppDomain.CurrentDomain.BaseDirectory, bin, string.Format({0}.XML, typeof(SwaggerConfig).Assembly.GetName().Name)); }这个时候代码基本完成了还需要我们通过vs设置一下生成项目时自动创建xml文件如下鼠标右键起始项目-》属性-》生成-》勾选xml文件 然后鼠标右键重新生成下项目这个时候bin目录就有了WebApplication.xml 这个xml文件内容就是一些注释的信息具体各位自己点看看下xml内容到这里我们设置和代码都弄完了来看下swagger页面效果通过预览 http://localhost:51847/swagger/ui/index 这个时候我们增加的一些文字说明就完成了这个时候细心的朋友能够看出来我们的Action方法名称没识别出来这不符合我们命名规范这里有两种解决方案在action方法上增加 [ActionName(Login)] 标记修改WebApiConfig.cs文件的路由如api/{controller}/{action}/{id} 这里我采用后者为了统一通过方法名来识别对应接口 swagger文档支持在header中增加Token参数 对于api接口我们通常在登录后的其他操作都会让调用方传递授权的token而token一般做法是放在请求的header里面swagger文档为了测试方便可以把token放在header作为参数传递首先创建测试接口GetNames/// summary /// 获取用户名称列表 /// /summary /// returns/returns [HttpPost] public Liststring GetNames() { Liststring list new Liststring {神牛001,神牛002, 神牛003 }; return list; }然后在App_Start/SwaggerConfig.cs文件中添加1 c.ApiKey(apiKey)2 .Description(授权token)3 .Name(token)4 .In(header); 并启动1 EnableSwaggerUi(c 2 { 3 c.EnableApiKeySupport(token, header);4 }); 然后启动并在swagger界面输入 这个时候点击try it out请求接口能够在看到请求里面包含了token信息 原文地址: https://www.cnblogs.com/wangrudong003/p/9010108.html.NET社区新闻深度好文欢迎访问公众号文章汇总 http://www.csharpkit.com
