程序员不得的不会的接口文档

原文链接:https://juejin.im/post/5ce50f7851882533287a78ca

程序员不得的不会的接口文档

一、传统方式

众所周知,我们Java程序员在写完数据接口之后,想要前端或者App工程师调用的,需要写出接口文档,方便描述每一个接口都是干什么的,需要什么,怎么请求,返回的结果又是什么?可是现在的你是否还在手写接口文档呢?在手写接口文档中,有没有遇到,文档刚写好,测试反馈接口有问题,又不得不改写接口,结果接口改完之后,发送文档对不上了,怎么办?

我在工作中,是如何编写接口文档的呢?接下来给大家聊一神器,惊喜在后面。

首先,我新建一个项目,基于Spring Boot,开发几个接口,发布运行。

编写代码,实现2个数据接口,一个Post请求,新增,一个Get请求实现查询


运行项目,并测试接口

按照传统方式,项目写完了是不是要写接口文档?传统的接口文档就是如下所示:

接口:用户数据查询

地址:http://localhost:8080/user/all.do

请求方式:GET

请求参数:无

返回格式:JSON

返回数据参考:

二、Swagger

可是现在突然接口发生了变化?怎么办?是不是要去改动接口,再来改动文档?那么今天咱们用Swagger来接口数据接口改动对接口文档的影响。

Swagger最受欢迎的REST APIs文档生成工具之一,可以生成一个具有互动性的API控制台,开发者可以用来快速学习和测试API。

那么Swagger如何应用?接下来三部曲:

依赖jar

配置注解

在对应的数据接口上使用以下注解:

@Api修饰类 标记这个类是做什么的

@ApiOption 修饰方法,标记这个映射方法是解决什么问题的

启用Swagger

在SpringBoot的开关类上使用注解@EnableSwagger2

重新运行项目,在浏览器访问swagger-ui.html页面,可以看到如下内容:

我们可以看到刚刚咱们写的2个接口,请求方式、路径、做什么的是不是都可以清晰的看到?那么我们再来进行下面的测试接口:

总结

其实Swagger重要的2个作用:1、显示目前项目的所有数据接口信息包含路径、参数、返回格式、数据模型,2可以进行在线接口测试,完美解决后端工程师的难题,你会了吗?




展开阅读全文
博主设置当前文章不允许评论。

一个新手程序员不得不说的...

01-11

一个项目做到现在,告一小结,主要的就是页面的问题了。所以闲下来写点东西。rn我是今年毕业的,算是新手了.在学校时从来没想过自己会走道程序员这一步,可谁知鬼使神差的走成了现在。不知道自己是否适合做这个。rn作为新手,现在想说的就是在开发时所受到的委屈和冷眼,也许太言重了。rn不知道大哥们当初刚走上这条路时,是否会碰到类似我这样的情况呢?rn本身刚开始起步,很多问题就摆在了面前。我也知道要慢慢来,慢慢去学习,努力去学习,毕竟刚开始还有很多不懂得。但事实是没有时间让你去思考,你必须尽快上手,尽早做事情。作为新手每天每时都会碰到迷惑。但没时间去想为什么,你只有去做。碰到问题,花费多倍于人家的时间去做,最后还不一定是正确的,还会对你说你做的对吗,做的是什么呀!自己只能忍气吞声,因为你有愧于技术员这个称谓,有愧于给你的工资.虽然多数情况下,他还是会告诉你,我也会领情,自己心里反感到很感激.开发项目真的很哭.rn不知道你开始工作时,开始走上程序员时,面临的是什么?也是这样的无奈吗?请有经验的大哥们照顾新手一下.让我们以平常心一起共事,将来我们会清晰的记得你当初的慷慨,我们会把你的荣耀传下去...rn 论坛

没有更多推荐了,返回首页