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

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

一、传统方式

众所周知，我们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可以进行在线接口测试，完美解决后端工程师的难题，你会了吗？