本次和大家分享的是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风格文档的更多相关文章

  1. springmvc+swagger构建Restful风格文档

    本次和大家分享的是java方面的springmvc来构建的webapi接口+swagger文档:上篇文章分享.net的webapi用swagger来构建文档,因为有朋友问了为啥.net有docpage ...

  2. Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档

    前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...

  3. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

  4. Spring Boot中使用Swagger2构建RESTful API文档

    在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...

  5. Spring Boot中使用Swagger2构建强大的RESTful API文档

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  6. 使用Swagger2构建强大的RESTful API文档(1)(二十二)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

  7. Spring Boot 中使用 Swagger2 构建强大的 RESTful API 文档

    项目现状:由于前后端分离,没有很好的前后端合作工具. 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型.HTTP头部信息.HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下 ...

  8. SpringBoot_06_使用Swagger2构建强大的RESTful API文档

    二.参考资料 1.Spring Boot中使用Swagger2构建强大的RESTful API文档 2.

  9. Spring Boot教程(二十二)使用Swagger2构建强大的RESTful API文档(1)

    由于Spring Boot能够快速开发.便捷部署等特性,相信有很大一部分Spring Boot的用户会用来构建RESTful API.而我们构建RESTful API的目的通常都是由于多终端的原因,这 ...

随机推荐

  1. iOS体会篇 大学编程到公司的过程

    原文作者:朱众 授权本技术博文转载. 刚进公司时,在你正式动手写代码前,很可能要理解code base.这一过程至少持续1个月,取决于你所在项目的规模.你会发现你不得不使用你浑身所学之能事,理解上古程 ...

  2. JAVA之旅(二十)—HashSet,自定义存储对象,TreeSet,二叉树,实现Comparator方式排序,TreeSet小练习

    JAVA之旅(二十)-HashSet,自定义存储对象,TreeSet,二叉树,实现Comparator方式排序,TreeSet小练习 我们继续说一下集合框架 Set:元素是无序(存入和取出的顺序不一定 ...

  3. 动态创建VIEW

    很多人都应该知道 global temporary table 的用法,这里也提出一个动态VIEW的用法,在实际过程中有着很好的独特之处 具体如下: /***************创建PACKAGE ...

  4. MySql my.ini 中文详细说明

    [mysqld] port           = 3306 socket         = /tmp/mysql.sock # 设置mysql的安装目录 basedir=F:\\Hzq Soft\ ...

  5. “基于数据仓库的广东省高速公路一张网过渡期通行数据及异常分析系统"已被《计算机时代》录用

       今天收到<计算机时代>编辑部寄来的稿件录用通知,本人撰写的论文"基于数据仓库的广东省高速公路一张网过渡期通行数据及异常分析系统",已被<计算机时代>录 ...

  6. 学习pthreads,管理线程的栈

    进程的地址空间分成代码段,静态数据段,堆和栈段.线程栈的位置和大小是从它所属的进程的栈中切分出来的.每个栈必须足够大,以容纳所有对等线程的函数的执行以及它们将会调用的例程链.或许你会问为什么要进行线程 ...

  7. 网站开发进阶(三十)HTML5--本地存储Web Storage

    HTML5--本地存储Web Storage Web Storage功能,顾名思义,就是在Web上针对客户端本地储存数据的功能,具体来说Web Storage分为两种: sessionStorage: ...

  8. 【翻译】Ext JS——高效的编码风格指南

    原文:ExtJS - Efficient coding style guide 作者:Raja 切勿使用"new"关键字:在Ext JS中,使用"new"关键字 ...

  9. LIRe 源代码分析 6:检索(ImageSearcher)[以颜色布局为例]

    ===================================================== LIRe源代码分析系列文章列表: LIRe 源代码分析 1:整体结构 LIRe 源代码分析 ...

  10. 【Android 应用开发】OpenGL ES 2.0 -- 制作 3D 彩色旋转三角形 - 顶点着色器 片元着色器 使用详解

    最近开始关注OpenGL ES 2.0 这是真正意义上的理解的第一个3D程序 , 从零开始学习 . 案例下载地址 : http://download.csdn.net/detail/han120201 ...