使用Swashbuckle构建RESTful风格文档
本次和大家分享的是Swagger to WebApi的nuget包Swashbuckle;因为项目需要统一api文档的风格,并要支持多种开发语言(C#,java,python),所以首先想到的是swagger来构建api文档,本章讲解的是对.net的webpi来生成文档,后续会将java的springmvc+swagger来构建接口文档。
- 准备工作
- 快速构建简易api文档
- swagger文档支持在header中增加Token参数
. 准备工作
首先创webapi项目,然后通过nuget管理器安装Swashbuckle的包,我这里通过console命令安装:
Install-Package Swashbuckle -Version 5.6.
注意只需要安装这个包就行了,其他的会自动引用,由于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 name="rq">请求</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 List<string> GetNames()
{
List<string> list = new List<string> {"神牛001","神牛002", "神牛003" }; return list;
}
然后在App_Start/SwaggerConfig.cs文件中添加:
c.ApiKey("apiKey")
.Description("授权token")
.Name("token")
.In("header");
并启动:
EnableSwaggerUi(c =>
{
c.EnableApiKeySupport("token", "header");
});
然后启动并在swagger界面输入:
这个时候点击try it out请求接口,能够在看到请求里面包含了token信息:
使用Swashbuckle构建RESTful风格文档的更多相关文章
- springmvc+swagger构建Restful风格文档
本次和大家分享的是java方面的springmvc来构建的webapi接口+swagger文档:上篇文章分享.net的webapi用swagger来构建文档,因为有朋友问了为啥.net有docpage ...
- Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档
前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...
- springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
- Spring Boot中使用Swagger2构建RESTful API文档
在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...
- Spring Boot中使用Swagger2构建强大的RESTful API文档
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- 使用Swagger2构建强大的RESTful API文档(1)(二十二)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
- Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档
项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...
- SpringBoot_06_使用Swagger2构建强大的RESTful API文档
二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.
- Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)
由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...
随机推荐
- Linux信号实践(1) --Linux信号编程概述
中断 中断是系统对于异步事件的响应, 进程执行代码的过程中可以随时被打断,然后去执行异常处理程序; 计算机系统的中断场景:中断源发出中断信号 -> CPU判断中断是否屏蔽屏蔽以及保护现场 -&g ...
- spring4泛型初探----一个小例子
泛型的出现,是为了让代码更规整. 例如 Set<String> set=new HashSet<>(); set.add("abc"); set.add(1 ...
- 【leetcode73】经典算法-Guess Number Higher or Lower
题目描述: 从1-n中,随便的拿出一个数字,你来猜测. 提示 提供一个guess(int num)的api,针对猜测的数字,返回三个数值.0,-1,1 0;猜中返回num -1:比猜测的数值小 1:比 ...
- 【一天一道LeetCode】#74. Search a 2D Matrix
一天一道LeetCode 本系列文章已全部上传至我的github,地址:ZeeCoder's Github 欢迎大家关注我的新浪微博,我的新浪微博 欢迎转载,转载请注明出处 (一)题目 Write a ...
- FT5X06 如何应用在10寸电容屏(linux-3.5电容屏驱动简析&移植10寸电容屏驱动到Android4.2) (by liukun321咕唧咕唧)
这是几个月以前的东西了,在彻底遗忘之前拿出来好好写写.做个笔记,也算是造福后来人了.在做这个项目之前,没有做过电容屏的驱动,印象中的电容触摸屏是不需要校正的.IC支持多大的屏就要配多大的屏.但是拿到需 ...
- GIT版本控制 — 简介与安装 (一)
简介 GIT与SVN的区别 作为当前最流行的版本控制系统,Git和SVN的几个主要不同之处在于: (1) Git是分布式的版本控制系统,SVN是集中式的版本控制系统.Git可以先把修改提交到本地仓库中 ...
- C++对象模型(二):The Semantics of Copy Constructors(拷贝构造函数之编译背后的行为)
本文是 Inside The C++ Object Model's Chapter 2 的部分读书笔记. 有三种情况,需要拷贝构造函数: 1)object直接为另外一个object的初始值 2)ob ...
- Live555 直播源 以及MediaSubsession
/* * H264DeviceSource.hh * * Created on: 2014年7月19日 * Author: zjzhang */ #ifndef H264DEVICESOURCE_HH ...
- 学习pthreads,使用属性对象创建结合线程和分离线程
当我们创建了子线程,是让它犹如脱缰之马,信步驰骋,还是如乖巧听话的孩子,时不时教导一下呢?针对这个问题,本文介绍线程的结合和分离,结构分为三个部分,第一部分给出代码示例,第二部分对代码进行讲解,第三部 ...
- [Redis]处理定时任务的2种思路
用redis完成类似 at 命令的功能,例如订单24小时后没有支付自动关闭,定时发邮件,主要说下任务生成之后怎么触发消费. 使用 有序集合 思路: 使用sorted Sets的自动排序, key 为任 ...