前言
本文主要阐述如何通过easyhapi插件快速导出Java接口为YAPI文档。
注:YAPI 是一个高效、易用、功能强大的可视化接口管理平台,主要用于 API的开发、测试和文档管理。它提供了一个直观的界面来创建、编辑和删除接口,使得开发者可以方便地管理项目的各种 API。平台内置了自动化测试工具,允许用户编写和执行测试用例,以确保 API 的正确性和稳定性。
YAPI 支持数据 Mock 功能,可以在开发过程中模拟后端服务的响应,帮助前端开发者独立进行开发和调试。基于定义的接口信息,YAPI 可以自动生成详细的 API 文档,包括请求参数、响应格式和示例等,便于团队成员和外部开发者参考。支持接口版本管理,允许开发者为不同的项目阶段或迭代创建和管理多个 API 版本。
YAPI提供灵活的用户权限系统,可以根据角色和职责分配对 API 和项目的访问权限。YAPI 是一个开源项目,通过使用 YAPI开发团队能够更加高效地管理和维护 API,提高开发速度,减少错误和沟通成本,并为用户提供高质量的 API 文档。
yapi创建项目
首先打开yapi,我们点创建项目
给项目取个名字,然后点击创建项目
创建成功之后可以看到项目还是空的
EasyYapi安装与配置
EasyYapi插件是为Java开发设计的接口文档生成工具,它与YAPI接口管理平台集成,旨在简化API接口的开发和文档编写过程。
EasyYapi插件能够自动扫描和解析Java代码中的注释和方法签名,根据这些信息自动生成符合YAPI格式的接口文档,减少了手动编写文档的工作量和出错的可能性。该插件与YAPI接口管理平台深度集成,生成的接口文档可以直接导入到YAPI中,方便团队成员查阅、测试和管理API。
EasyYapi插件在IDE(如IntelliJ IDEA)中易于安装和配置,只需搜索并安装插件,然后进行简单的设置即可开始使用。插件支持常见的Java注解,如@Api、@ApiOperation等,可以根据这些注解来提取接口的元数据和描述信息。每当Java代码发生变化时,EasyYapi插件可以自动检测并更新相应的接口文档,确保文档始终保持最新状态。由于接口文档是基于代码注释生成的,因此当代码发生变化时,只需要更新注释即可同步更新文档,使得文档维护变得更加简单。
在Settings/Plugins中是搜索 EasyYapi ,我们直接安装
随后到Settings/Other Settings/EasyApi中,在Yapi配置栏下,输入你自己YAPI的server地址和token。
需要注意,关于server地址:打开一个项目之后,url结构为 server地址/project/项目号/...
因此这里的server地址是url中 /project/项目号/...
之前的字符串
token可以到项目界面下,设置/token配置 当中去复制。
导出接口文档
之后我们打开IDEA,在一个controller下,右键controller文件,或者右键点击编辑界面空白处,选择Export Yapi,第一次导出需要输入一次token,直接把刚刚复制的token复制进去即可。
可以看到控制台显示导出成功:
回到YAPI中,可以看到我们导出的接口文档:
可以看到注释比较乱
注释
之前yapi注释没有写好,重新规范一下注释,提高可读性。注释直接使用java原生注释即可,
我这里写了一个可以参考:
package org.sample.controller;
import org.sample.common.request.PageRequest;
import org.sample.common.response.Response;
import org.sample.common.response.ResponseGenerator;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.io.IOException;
/**
* 测试模块
* @author aaa
* @since 2020/6/5
*/
@RestController
public class HelloController {
/**
* 诗词朗诵接口
* 打印字符串
* @param id 用户id
* @param pageRequest 分页请求
* @return Response
* @throws IOException
*/
@RequestMapping("/say-hello")
public Response sayHello(@RequestParam("id") String id, @RequestBody PageRequest pageRequest) throws IOException {
Response response = ResponseGenerator.genSuccessResponse(pageRequest);
return response;
}
}
package org.sample.common.request;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.io.Serializable;
/**
* 分页查询请求
* @author aaa
* @since 2022-06-01
*/
@Data
@EqualsAndHashCode
public class PageRequest implements Serializable {
private static final long serialVersionUID = -3772068300449489722L;
/**
* 页码,默认是1
*/
private Integer pageNo = 1;
/**
* 页大小,默认是10
*/
private Integer pageSize = 10;
/**
* 消息是否已读,0-未读, 1-已读, null-未读+已读
*/
private Integer read;
}
生成之后:
注意这里的创建人是与yapi账号绑定的,和代码注释的@author 无关
总结
EasyYapi插件是一个实用的工具,可以高效地管理和维护API接口文档,同时促进了团队之间的协作和沟通。通过与YAPI接口管理平台的集成,它提供了完整的接口开发和文档管理解决方案。通过自动化文档生成和集成YAPI平台,EasyYapi插件可以帮助开发者更快地完成接口开发和文档编写工作,提高整个项目的开发效率。
参考
https://www.cnblogs.com/allennote/articles/13154983.html