Yapi文档的使用
一、原来已经有了Rap,为什么要用Yapi?
答：可以使用插件根据代码注释和接口文档同步更新，既保持了代码注释的更新维护，也减少接口文档录入和更新时间。
二、Yapi的注册使用
- 使用地址: http://120.77.133.46:8002/，输入真实姓名和邮箱注册
- 使用文档地址: https://hellosean1025.github.io/yapi/documents/index.html
三、Yapi插件在IDEA中的使用
4. 在idea 插件库中搜索 YapiUpload安装，当前版本1.7.8
5. 如果是下载的jar 需要 打开idea preferneces->plugins-> install plugin from disk,导入jar 包后(install)，重启
6. 配置信息
3.1 配置信息位置, 在项目目录下，.idea 文件夹下，找到misc.xml (如果找不到.idea 请查看是否被折叠或被隐藏) 如果是 .ipr 模式创建的 就找到 项目名.ipr
3.2 单模块配置
获取token值和项目配置的端口号和地址
填写的地址在：项目中idea中的misc.xml，这里也可以查看web段的名称
填写的格式：
token
36
address
api
openBoot,moduleName2
3.3多模块配置 （建议使用,这个可以结合最后的示例Test类，修改boyun为ModuleName用来测试）
boyun,moduleName2
3.4 各个参数获得
• token 获取方式： 打开yapi ->具体项目->设置->token 配置
• 项目id 获取方式：点击项目，查看url 中project 后面的数字为项目id http://120.77.133.46:8002/project/72/interface/api 这个id为72
• yapiUrl 获取方式：部署的yapi 地址，bsj的地址为http://120.77.133.46:8002
• projectType 填写方式： 根据你要上传的接口类型决定，如果为dubbo 接口就填dubbo ，如果是api 接口就填api
• attachUploadUrl 填写方式:上传java 类zip 的url,如果要用请实现http://localhost/fileupload 接口 接口请求参数为 file 文件类型。(可不填，我们用不到删除了)
• returnClass 填写方式:统一返回对象的全路径（1.7.4及之后支持,之前版本可不配)
• moduleList 获取方式：模块名称，用 “,” 分割 ，不支持父节点和子模块名称一样的情况
3.5 上传
如果是dubbo 项目，选中dubbo interface 文件中的一个方法（要选中方法名称），右击YapiUpload(alt+u 快捷键)
如果是api 项目，选中controller 类中的方法名称或类名（要选中方法名称，或类名，选中类名为当前类所有接口都上传），右击YapiUpload(alt+u快捷键)
1.7.4 及之后的版本 如果未选择任何地方 上传 默认按类上传
Yapi插件使用规则
注意点: 良好的java doc 注释能生成更好的文档
1.插件如何生成属性备注 ,通过获得字段备注中的注释（使用多行注释）
/**
* 年龄
*/
private Integer age;
2.插件如何生成接口名称，通过接口上的注释，或者引用上的 注释（建议使用第一种）
/**
* 接口名称（第一种方式，或者使用@description）
*
* @description: 第二种方式(@Description 也可）
* @param uid 用户id
* @param str 备注
* @return
* @status done
* @path /http/test/testRequestDesc5.json
*/
public Integer testRequestDesc5(Integer uid, String str, Duser duser){
3.@link 参数定义展示在字段备注中（建议使用第一种）
{@link}的作用:把内容相互关联起来，方便自己或别人看的时候，可以直接找到你关联的代码类(和@see的作用差不多，@see只能顶头写)
第一种@link 方式
/**
* 状态 {@link com.xxx.constant.StatusConstant}
*/
private Integer status;
第二种@link 方式
import com.xxx.constant.StatusConstant;
/**
* 状态 {@link StatusConstant}
*/
private Integer status;
不支持方式
import com.xxx.constant.*;
/**
* 状态 {@link StatusConstant}
*/
private Integer status;
4.实现自定义分类（建议使用在类上）
通过在方法或类注释中加 @menu 注释实现，优先级 方法>类>package 下面或者上面的@menu,如果没有自定义 默认为tool-tmp,
/**
* 测试上传接口文档
*
* @author
* @menu 测试分类
* @date 2020-02-15 11:31
- 支持@status注解
支持已发布(done),开发中(undone),支持中英文，新增接口默认 开发中,更新时如果没有写status情况下默认使用当前状态
/**
* 测试开发完成
*
* @param uid 用户id
* @param str 备注
* @return
* @status done
* @path /http/test/testRequestDesc5.json
*/
public Integer testRequestDesc5(Integer uid, String str) {
- 项目中通过fitler或拦截器或注解等，实现全局统一响应对象
返回如何处理,在misc.xml 中配置 returnClass ，值为全局统一响应对象全路径。比如下面代码如果配置了returnClass 为GlobalResponse ,那么他生成的yapi 响应对象为，GlobalResponse
/**
* 测试RequestHeader desc 规范的多个
* @param uid 用户id
* @status 开发中 (或者 undone)
*/
@RequestMapping(value = "/testRequestDesc4")
public Integer testRequestDesc4(@RequestHeader(name = "uid")Integer uid){
}
public class GlobalResponse<T> {
private String status;
private String code;
private T data;
......
}
7.支持@path
目前 1.7.8及以上支持 在方法上指定路径，通过@path 注释,如下代码，其生成的路径为/path/test/testRequestDesc5.json
/**
* 测试开发完成
*
* @param uid 用户id
* @param str 备注
* @return
* @status done
* @path /http/test/testRequestDesc5.json
*/
public Integer testRequestDesc5(Integer uid, String str, Duser duser,
HttpServletRequest request, HttpServletResponse response) {
- 完整使用示例（结合多模块配置使用）
package com.bsj.boyun.main.module.screen.http;
import com.bsj.common.def.Duser;
import com.bsj.common.def.RetObj;
/**
* 测试上传接口文档
*
* @author
* @menu 测试分类
* @date 2020-02-15 11:31
**/
public class Test {
/**
* 测试不写状态，默认为未完成
*
* @param uid 用户id
* @param str 备注
* @param duser 用户信息
* @path /http/test/testRequestDesc4.json（非SpringBoot项目才用）
*/
public Integer testRequestDesc4(Integer uid, String str, Duser duser) {
return 1;
}
/**
* 测试开发完成
*
* @param uid 用户id
* @param str 备注
* @return Integer
* @status done
* @path /http/test/testRequestDesc5.json
*/
public Integer testRequestDesc5(Integer uid, String str) {
return 1;
}
/**
* 测试未完成
*
* @param duser 用户信息
* @return {@link com.bsj.common.def.RetObj}
* @status undone
* @path /http/test/testRequestDesc6.json
*/
public RetObj testRequestDesc6(Duser duser) {
return new RetObj();
}
}
五、参考文档
- Yapi官方Github：https://github.com/YMFE/yapi
- 快速使用idea插件一键上传接口到Yapi：
https://github.com/diwand/YapiIdeaUploadPlugin/wiki/%E5%BF%AB%E9%80%9F%E4%BD%BF%E7%94%A8