【YAPI】【IDEA】java接口直接导出为YAPI接口文档

前言

本文主要阐述如何通过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

https://zhuanlan.zhihu.com/p/500965600

https://easyyapi.com/documents/java_doc_demo.html