Swagger UI教程 API 文档神器 搭配Node使用

一、node.js的安装

运行环境必须使用node.js,把其作为服务器来跑，

安装教程

二、swagger的安装

教程



对上面的图片进行进行讲解，教程博客中大部分都讲清楚了，所以我这里就不说了，在我做的过程中就是这个地方没有看懂，我在这里进行解释一下，它讲的那个url是在public/index.html 文件中，把它替换为后边的就可以了，还有那个text.json名字要用自己的。

三、用法

使用 Swagger Editor 编写API文档，把写好的文档下载下来就可以跑了，若在公司里的话就把这个服务器安装在公有的服务器之上，把写好的接口文档提交上去，这样前后台就可以遵循着这种契约来进行写代码了。

四、Mock server 的使用

契约测试

谈到了前后端分离，那么在所难免，会遇到一些集成的问题：一拨人在全心全意的进行前端开发，另一拨人在心无旁骛的做后端开发，那么谁应该为集成买单呢？在现在这个持续集成、持续交付的年代里，我们应该如何去保证双方不会分道扬镳、越走越远呢？

所以，在一开始就定一个契约就成了迫在眉睫的事情，双方就API相关的内容，包括路径、参数、类型等达成一致，当然，这份契约并不是一旦创建就不能修改的，而且，如果一开始没有设计好，很有可能会频繁的修改。这个时候，要让双方都能够实时的跟踪最新的API就成了一个难题。还好，在总结了前人的经验和教训之后，我们早已有了应对之策，那就是契约测试。

老马（Martin Fowler）早在2011年的时候就发表了一篇博客http://martinfowler.com/bliki/IntegrationContractTest.html，专门讨论了如何做契约测试。

首先，我们先假设我们已经有了一份契约，可能是基于JSON格式的，有可能是基于XML格式的，这都不重要。然后，前端会根据这份契约建立一个Mock server，所有的测试都发往这个Mock server。有两方面的原因：一是这个时候可能后台的API还没有开发完成；二是有可能因为网络等其他方面的原因导致直接调用真实的后台API会很不稳定或者很耗时。到这里，可能有人就要说了，如果后台的API实现和之前约定的并不一样，怎么能保证到了集成的时候双方还能很顺利的集成呢？其实这个问题并不难，只需要让前端的测试定期连接真实的API执行一遍就能尽早的发现差异性。比方说，在我们平常的build pipeline上添加一个job，让这些测试每天在午夜里连着真实的API执行。如果，第二天发现这些测试有的失败了，那么就需要和开发后台API的人员进行一次沟通了，很有可能由于真实的业务逻辑发生了变化，API在实现的时候，已经和之前的契约不一致了，如果是这样，那么相应的测试和契约定义就需要更新以满足最新的业务需求。

总之，进行契约测试的目的就是尽早的发现差异性，并作出调整，将最后集成的风险降到最低。

总结：我写这篇文章的目的是想学习以下几个知识点

1、就是一个前后台的API规范问题，这个我已经学到了，就是大家都常用的 RESTFul （这是一个优秀的个人博客讲解RESTful API 设计指南的）接口格式

2、我想知道如何使用swagger软件写出符合json格式的 RESTful 接口文档，这个我也差不多会了。

3、我想要学习如何使用swagger编写契约测试，这点我没有学会，有会的望指点一下。

RESTful 架构

1、REST（表现层状态转换） 把资源呈现出来的形式叫做它的表现层，状态转换就是让服务器数据发生转换

2、设计一套合理好用的API