什么情况适合使用swagger?

今天我想把以前一直在用的swagger推荐给公司团队,结果发现其实在很多方面,swagger并不能给工作带来的实际帮助。

只针对于swagger的自动生成接口文档,不包括swagger editor。

 

1.软件工程流程

受dalao启发,现在我认为的标准的工作流程如下:

1.需求分析(产品经理理解需求,构造原型,给开发人员讲解)

2.进行接口设计(同时写接口文档,原则上接口定下来就不能改动了(因为不是敏捷开发))

3.设计测试用例(提早设计测试用例,利于设计人员想清楚实现的细节)

4.后端提供模拟数据 (如果有接口工具,就无需后端提供模拟)

5.前端根据模拟数据进行开发,同时后端也进行编码 

6.根据测试用例,进行单元测试(要写单元测试代码)

7.前后端联调

8.前后端总体测试

这个流程和普通的开发流程有些不一样,是我从dalao那学来的。果然软件工程很注重工作经验,有经验的开发人员思考得就是全面。

下面是我认为的要点:

(1)需求分析需要核心人员在场。包括核心开发人员,项目管理人员。

根据《没有银弹》,软件设计应该由核心人员设计,保持设计理念,不让太多人参与。

似乎很多时候,需求分析只由产品经理完成,然后设计原型,讲解给开发人员。

但是我不认为需求分析就只是产品经理的事。每个人都有自己对需求的看法,所以听取核心人员的意见也许有利于完善初始的原型设计(前提是他们有这个时间,有可能要开个小会)。

但是最终拍板的还是产品经理。多人参与设计可能会干扰产品经理的判断。所以这就要求产品经理在听取他人意见的同时,保持着自己的主张,能够一锤定音。

(2)接口设计需要前后端开发人员和项目管理人员同时在场。

我觉得很多时候接口的质量严重依赖于后端人员的设计能力。往往是后端人员完成设计,完成接口文档的编写。拿到定好的文档之后,前端人员才能开始工作。

但是,在此同时,前端人员会比较清楚自己想要展示些什么数据。所以我觉得前端人员应该加入接口设计环节,向后端人员“要数据”,有助于后端人员理清接口结构,了解自己要怎么去实现接口。

我认为这个环节基本上就是一个讨论环节。前后端人员在商议接口设计时,往往会提及实现难点。项目管理人员就可以根据讨论结果制定项目周期,进行计划。

(3)设计测试用例要提早做

很多人往往是已经完成了编码之后,才开始设计测试用例,用于单元测试。其实这个步骤完全可以提前。因为测试用例中涉及诸多实现细节,所以在设计时,有利于帮助后端人员提前理解自己要做什么,怎么做,而且还能查漏补缺。

(4)一定要进行单元测试

调通接口,根本不是测试。一定要进行单元测试。我知道单元测试很复杂,很花时间,很烦。但是单元测试的覆盖面最广,结果最可靠,最能证明你的代码没问题。而且最重要的是,只是调通接口,可谓是口说无凭。后端开发人员要展示自己准确无误的工作成果,必须通过单元测试的代码去自证:我写的东西一点问题都没有,工资要按时给我哦。

(5)接口文档的编写

无论使用什么工具,是用什么格式来写接口文档,标准都差不多。基本上包括:模块名称,接口功能,接口地址,参数解析,返回结果解析。我觉得最好还要加上实际调用示例。

接口文档只能有一份,保证每个开发人员手中的文档都是最新的。避免因为版本不同而出现兼容问题

(6)最耗时间的步骤

我认为最耗时间的步骤有:整个需求分析,整个接口设计,设计测试用例,测试。

总之最耗时间的地方集中在设计和测试两方面,编码倒是其次。

除此之外,最最耗时间的步骤就是返工!因为设计不当/需求不当造成的返工严重浪费工时,间接造成了开发人员的加班和猝死。

所以我们要尽量在需求分析和接口设计中下大功夫,保证整个开发流程的上游不出大问题,从而减少返工,让每个开发人员都能安全按时回家。

2.现在来看看swagger能给这个工作流程带来了什么好处

想要使用swagger,当然需要找到其优越之处,才有使用的价值。

(1)swagger只需要在代码中使用注解,就能自动实现接口文档,节省了写文档的时间

首先我们要明确写接口文档的意义是什么。是为了让开发人员仔细设计接口,然后写成文档,让前后端能根据文档有目的地进行开发。接口设计在软件工程的上游是特别重要的存在。写接口文档其实是为了让开发人员在接口设计的过程中更加小心翼翼,思考全面,避免因为设计不当而在之后出现返工的悲剧。

举个例子:

因为swagger可以省掉写接口文档的功夫,我的整个接口设计过程就没那么认真了。我开始边设计便进行编码(这就是之前的我),反正写完之后会自动出文档,那干脆写完再说吧!

这会导致什么结果呢?

很可能因为设计不当,考虑得不详细,造成返工,损失惨重。如果写接口文档,往往就能详细考虑,正确设计,开发速度比返工还快!

我知道写接口文档很痛苦(即使有工具支持),也知道swagger确实非常方便,但是仔细设计接口的这个过程是绝对不能省去的。这直接决定了工作的质量。

(2)swagger提供了测试功能,可以测试接口

首先,这个所谓的“测试功能”并不是真正的测试,等同于“调通了接口”如果认为这个就是单元测试,那就大错特错了。

举个例子:

反正swagger测试方便,我干脆连设计测试用例的步骤都省了。每次用swagger,只是输几种情况,看到返回正常,就认为这个功能测试通过了,并不对测试用例和返回结果做任何的记录。

这会导致什么结果呢?

没有认真设计测试用例,万一有特殊的情况没有测试到,怎么办?没有测试用例和返回结果的记录,除了你自己,别人怎么知道这个接口有没有被测试过?要怎么证明这个接口能正常工作?因为没有写单元测试的代码,如果要重新进行测试怎么办?每次都去重头开始测试吗?

比较负责任的单元测试需要完整的测试代码,完整的测试用例,并且记录测试用例和返回结果,最后才能证明这个功能是否能正常工作。

(3)swagger很即时,写完代码就出结果

swagger是要跑在服务端中,那些接口才可以被访问的。那么如何时刻保证swagger中的接口都是最新并且唯一的?

而且,软件工程往往是多人协作,前端人员到底要看谁提供的swagger呢?万一之前的接口被更改了,但是因为当前服务端没有及时更新,变更的接口并没有体现出来,前端人员可能就一直在基于错误的接口进行开发了。

(4)总结

现在反问一下自己:在这个体系中,swagger究竟能简化什么工作?

从以上三点,可以发现swagger并不能节省什么工作量,并不能代替最耗费时间的步骤。反而,一旦依赖工具,最能保证软件工程质量的步骤很可能被没经验的开发人员省去,造成各种各样的问题。

3.难道swagger真的是一无是处吗?

swagger有其适合使用的场景。

举两个例子:

(1)敏捷开发

现在有一个项目,因为客户并不知道自己真正需要什么,所以需求经常改变。如果要按照上面的系统的开发流程,一旦上层需求出现问题,下面的所有步骤都需要变动。接口需要改,文档需要更新,代码需要改,测试用例需要重写,测试需要重新测。如果这种变动非常频繁,开发人员怎么受得了?

所以这时候就提倡敏捷开发。比如说某个模块经常有改动,那么实际上开发人员并不能把太多的精力花费在标准的开发流程中,只要快速实现,以后的功能总是可以慢慢完善的。这时候,swagger的价值就体现出来了。自动生成文档,文档跟着代码走。既能做接口文档,又能简单测试数据。

注:敏捷开发以用户的需求进化为核心,采用迭代、循序渐进的方法进行软件开发。在敏捷开发中,软件项目在构建初期被切分成多个子项目,各个子项目的成果都经过测试,具备可视、可集成和可运行使用的特征。换言之,就是把一个大项目分为多个相互联系,但也可独立运行的小项目,并分别完成,在此过程中软件一直处于可使用状态。

(2)个人开发、小团队开发

个人和小团队开发往往有个特点:参与开发人数少,沟通成本低,精力往往要放在快速实现功能上。(团队太小,或者水平有限)

因此,设计过程和测试过程可能都会被精简,偏向于从编码中发现问题然后进行修改。实现功能后只进行简单测试,没有完整的单元测试流程。

这个开发流程和敏捷开发有些相似。

在这两种情况下,swagger都是一款优秀的工具。

4.现在回顾一下之前的“标准软件开发流程”

我们可以发现,这个流程跟敏捷开发的理念不同,比较趋于传统。适用于这种流程的项目,需求基本不会改动。下层的步骤基本也不会有改动,所以并不特别需要swagger的灵活性。正因为需求不太会改动,所以完全可以对每个步骤精雕细琢。而且,因为每个步骤都需要求非常严谨,所以swagger也不能简化什么工作。

而且,这种工具容易让经验不足的开发人员省去重要步骤(还沾沾自喜地认为工具很好用),在考虑不周的情况下,反而会有副作用!

在这种传统开发的情况下,感觉就没有必要使用swagger了。

4.总结

总之,具体项目决定了其开发方式。一切都要具体情况具体分析。通过这次思考,我对软件工程的流程理解又加深了。

总之,软件工程是充满科学的,充满着前人的智慧。他们总结的流程,自然有其道理。不要老想着实用工具,简单开发,踏踏实实地严格遵守流程,往往可以事半功倍。

发表评论

电子邮件地址不会被公开。 必填项已用*标注