码迷,mamicode.com
首页 > 其他好文 > 详细

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

时间:2019-05-23 10:54:30      阅读:138      评论:0      收藏:0      [点我收藏+]

标签:ring   json   数据查询   怎么办   控制台   方便   开关   如何   学习   

一、传统方式

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

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

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

技术图片

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

技术图片

运行项目,并测试接口

技术图片

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

接口:用户数据查询

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

请求方式:GET

请求参数:无

返回格式:JSON

返回数据参考:

技术图片

二、Swagger

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

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

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

1、依赖jar

技术图片

2、配置注解

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

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

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

技术图片

3、启用Swagger

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

技术图片

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

技术图片

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

技术图片

三、总结

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

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

标签:ring   json   数据查询   怎么办   控制台   方便   开关   如何   学习   

原文地址:https://www.cnblogs.com/CQqf2019/p/10910517.html

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!