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 单模块配置

yapi 中项目token yapi 中项目id http://120.77.133.46:8002/ api (Spring项目全局异常拦截才配置，配置的是返回的Json包装类路径，如com.project.Response，不是请删除本配置)

获取token值和项目配置的端口号和地址
在这里插入图片描述
填写的地址在：项目中idea中的misc.xml，这里也可以查看web段的名称

填写的格式：

3.3多模块配置（建议使用,这个可以结合最后的示例Test类，修改boyun为ModuleName用来测试）

boyun,moduleName2

0b20b419da26abc1c1ce355b9f0ec1093d1f142b30848c57da38b906a7aae1bd 39 http://120.77.133.46:8002 api

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

lcl程序猿

发布了33 篇原创文章 · 获赞 0 · 访问量 1436

私信关注

猜你喜欢