前言
每个后端开发人员都有写文档的经历。从最开始的手写到配置swagger写文档或者其他相关jar包等。但是、阅读了这篇文章，你会发现一个写文档的新世界！！！不开玩笑，读完你就会把swagger当球踢！！！
-
本篇文章已Spring boot为例
-
该方法无任何代码入侵！似的，没有任何代码入侵没有看错
-
可以使用PostMan或者md展示。似的，它还能已json的形式导入PostMan。还能直接转成MD文档。但这不是重点！往下看
-
怎么办，我以前用得是swagger还能改吗？---> 当然可以，它还能导入swagger数据，不过这不重要 ---> 为什么呢？ ---> 说啦是注释写文档了，只要注释写的好，都不是问题
-
这么神奇，到底是个什么呢？---> idea插件啦。似的，插件！为什么没有代码入侵了？ 因为只是个插件，没有任何
滑稽配置
-
文章结尾追加mock各种用法以及一些注释小方法（必看）
解决方案
1.入正题,打开idea设置，找插件EasyYapi
下载、重启
2.idea配置就基本完成了、似得完成了，没想到吧。官方网站 ，当然这只是简单配置
3.简单用法、先说明转成PostMan和md用法、比较简单。
4.新建一个接口类，写好注释！！！ 重点、注释要写好，但也没那么复杂
- 接口类
/**
* 测试类专用接口
*
* @author zmj
* @date 2021-1-4
*/
@RestController
@RequestMapping(value = "/go")
public class AppController {
/**
* 数据、测试接口
*
* @param bean
* @return
*/
@PostMapping(value = "/test")
public RestBean test(@RequestBody IdBean bean) {
return null;
}
}
- 实体类
import javax.validation.constraints.NotNull; //注意这个NotNull包是javax的才能识别
public class IdBean {
/**
* 需要查询的公司id
* @mock 10295 //枚举用 @see 包名路径+类 ---> 个人看官网
*/
@NotNull
private int id = -1;
public int getId() {
return id;
}
public void setId(int id) {
this.id = id;
}
}
- 实体类(自己写的返回类、可以用泛型指示！似得可以用泛型指示，别问我什么是泛型！！！)
/**
* 用户、响应体
* 2020-12-1
*/
public class RestBean<T> {
//返回、结果
private int result;
//返回、信息
private String message;
//返回、值
private T data;
/**
* 代码、类型设置
*
* @param type
*/
public void setType(RestCodeType type) {
this.result = type.getCode();
this.message = type.getMessage();
}
/**
* 设置数据
*
* @param data
*/
public void setData(T data) {
this.result = RestCodeType.SUCCESS.getCode();
this.message = RestCodeType.SUCCESS.getMessage();
this.data = data;
}
public T getData() {
return data;
}
public int getResult() {
return result;
}
public String getMessage() {
return message;
}
}
5.接口类已经搞定了，接下里是如何生成接口了--->快捷键 alt+shift+e
操作1
6.这就是需要生成文档的接口列表(左侧菜单快捷键直接全局扫描所有接口)，扫描了当前类的所有接口。同时注释小窗口的下拉列表有三种 Yapi(后面讲)、postman、md文档(没什么好说的)，这里直接
先讲postman导入
7.选择postman、导出到某个位置（导出成功后是一个json，不局限于postman）,打开postman
步骤一
步骤二
步骤三
8.导入完成。（这还不是重点）
image.png
9.主要到这个@mock了吗？还有我代码里的注释了吗？
image.png
10.很遗憾postMan不能使用mockjs生成数据，难过...
11.不过没关系，接下来才是文档的重点--->YApi登场(不收费，放心甚至是开源了！！！)
Yapi使用文档
- 直接上成果图，没图先讲就是耍流氓！！！
图片一
图片二
1.Yapi用到的环境和工具 node.js mongodb 除此之外...没了
2.node.js直接百度下载安装，没什么可以说的。（新手去百度下）
3.npm i -g yapi-cli yapi的自动化安装工具 官方，安装比较简单，是在不懂可以百度，文档不多但是也不少
4.mongodb安装，这个数据库安装比较简单，下载安装运行完事（新手百度）
5.成型页面(可以多人组队)
image.png
6.创建一个Yapi项目
7.回到代码、快捷键--->这次选择Yapi，确认。这时候需要输入两个东西，一个是地址一个是token，地址是yapi网页地址（个人配置的），token如图
image.png
8.确认上传即可。
Ps
- 可能有些东西没在上面讲清楚。
- easyYapi识别的是注释，下面举例
- 实体类、接口需要的那种(可以在Yapi项目中添加的参数值)
//它是一个ID
String id;
String id; //这样也是一个ID
/**
* 这样也是一个ID
* @mock 可以理解为给参数定值(这就是值)
* @see 填枚举类的值(路径+类名),例com.xxx.xxx.类 --->枚举值
*/
String id;
- 接口类
/**
* 分类
* 描述(注意行数)
* @author 作者
* @ignore 此标注会被忽略，方法同理
* @date 日期 养成好习惯
*/
public class AppController
/**
* 接口名称
* 描述
* @undone （未完成接口标识，默认完成）
* @menu 分类
* @return
*/
@PostMapping(value = "/识别这种接口，看官网")
public 可以用泛型<类> name(@RequestBody 提交参数类 bean)
追加Mock与其他小方法
-
忽略对象小方法1，fastjson序列化不生效
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.google.gson.annotations.Expose;
...
@JsonIgnore //二选一(spring boot 使用jackson序列化)
@Expose(serialize = true) // 二选一，建议前者
private int obj； //在接口中我会被忽略-注意值也会被忽略掉
-
忽略对象小方法2，jackson序列化不生效
...
private transient int obj； //在接口中我会被忽略-注意值也会被忽略掉,transient 关键字
...
-
对象修改名称小方法
import com.google.gson.annotations.SerializedName;
...
@SerializedName("jbo")
private int obj； //在接口中我叫jbo
- mock的
@natural方法
/**
* 字段
* @mock @natural(0,10000) //自然数范围对象
*/
private int obj;
- mock的
@pick方法
/**
* 字段
* @mock @pick(中文,非中文) //随机挑选一个
*/
private String obj;
- mock的
@date方法
/**
* 字段
* @mock @date //随机日期，如1978-05-30
*/
private String obj;
- mock的
@timestamp方法
/**
* 字段
* @mock @timestamp //时间戳 秒 mtimestamp有问题不记录替代方案@timestamp@string("0",3)
*/
private long obj;
- mock的
@boolean、@float、@Interage、@string方法
/**
* 字段
* @mock @boolean //随机变量，后两则相似
*/
private boolean obj;
/**
* 字段
* @mock @float(3,9) //随机浮点范围
*/
private double obj;
/**
* 字段
* @mock @string("lower",1,8) //随机范围字符串 @string(3) 长度三位的随机字符串 @string("123",3) 在123字符池随机三位
*/
private String obj;
- 完结、撒花、喜欢的点赞
网友评论