前言

你有没有遇到过这种情况，接手的项目没有接口文档，老板突然有一天让你梳理出该项目的所有接口文档，你该怎么弄？有没有什么快速便捷的方式？是否可以通过代码直接逆向生成接口文档呢？方法当然有啦！！

IDEA集成EasyYapi插件

可以通过 IntelliJ IDEA 集成 EasyYpai 插件实现接口文档的快速生成，详细步骤如下：

①EasyYapi插件安装：打开Idea---> Preferences(Settings) ---> Plugins ---> 搜索 EasyYApi 插件，点击 Install 进行安装

②安装完成后重启Idea，插件生效

③EasyYapi插件配置：插件配置之前，您需要搭建好 Yapi 网站，具体安装步骤可自行上网查找。

打开Idea---> Preferences(Settings) ---> Other Settings ---> EasyYapi，配置Yapi的server地址，如http://localhost:9090

④EasyYapi生成接口文档：接下来就是见证奇迹的时刻，找到要生成接口文档的Controller，在类上鼠标右键，单击 EasyApi--->Export Api

在弹出的窗口中我们可以看到接口列表，点击绿色的小对勾，会提示我们输入Private Token

打开Yapi网站项目，找到设置--->token配置，复制token到idea窗口中，点击确定

我们可以看到控制台提示接口导出成功

打开Yapi网站，接口全部自动生成完成，包括接口分类、接口名称、接口地址、Mock地址、接口说明、请求参数Header、请求参数Body、返回数据、创建人、创建时间、是不是很方便快捷。

参考示例代码

接口文档的自动生成是有一定规则的，可以参与如下示例代码，也可以参考 EasyYapi官方网站说明 https://easyyapi.com/documents/index.html

【YapiTestController.java】

import com.busi.monitor.response.BaseResponse;
import com.busi.monitor.vo.InParamData;
import com.busi.monitor.vo.OutParamData;
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 javax.validation.Valid;

/**
 * 接口分类名称
 * 分类备注/描述：自动生成接口文档
 *
 * @author 八零后琐话
 * @date： 2023-06-17
 */
@RestController
@RequestMapping(value = "/easyApi")
public class YapiTestController {
    /**
     * testApi001接口名称
     *
     * 我是api接口描述，这个描述内容很长
     * @param param1 参数1的名称或描述
     * @param param2 参数2的名称或描述
     * @param param3 参数3的名称或描述
     * @return 响应描述
     */
    @RequestMapping(value = "/testApi001")
    public BaseResponse testApi001(
            @RequestParam long param1,
            @RequestParam(defaultValue = "八零后琐话") String param2,
            @RequestParam(required = false) String param3){
        // param2 可以用`@link`来表示当前参数的取值是某个枚举 {@link some.enum.or.constant.class}
        // param3 当目标枚举字段与当前字段名不一致,额外指定 {@link some.enum.or.constant.class#property1}
        return new BaseResponse<>(param2);
    }

    /**
     * testApi002接口名称
     *
     * 默认使用`application/x-www-form-urlencoded`，
     * 对于`@RequestBody`将使用`application/json`，
     * 可以用注解`@Deprecated`来表示api废弃，
     * 也可以用注释`@deprecated`。
     * @deprecated 改用{@link #testApi003(InParamData)}
     */
    @Deprecated
    @RequestMapping(value = "/testApi002")
    public BaseResponse testApi002(@RequestBody InParamData inData){
        return new BaseResponse<>(new OutParamData());
    }

    /**
     * testApi003接口名称
     * 我一个是测试接口，主要胜于生成接口文档
     */
    @RequestMapping(value = "/testApi003")
    public BaseResponse<OutParamData> testApi003(@RequestBody @Valid InParamData in) {
        return new BaseResponse<>(new OutParamData());
    }
}

【BaseResponse.java】

package com.busi.monitor.response;

import javax.validation.constraints.NotBlank;

/**
 * @description： 通用返回信息
 * @author： 八零后琐话
 * @date： 2023-06-17
 */
public class BaseResponse<T> {
    /**
     * 返回码 0000:成功，其他为失败
     */
    @NotBlank
    private String code;
    /**
     * 返回信息
     */
    @NotBlank
    private String message;
    /**
     * 扩展返回码
     */
    private String extraCode;
    /**
     * 扩展返回信息
     */
    private String extraMessage;
    /**
     * 返回详细信息
     */
    private T data;
    public BaseResponse(T data) {
        this.code = "200";
        this.message = "ok";
        this.data = data;
    }
}

【InParamData.java】

package com.busi.monitor.vo;

import javafx.beans.DefaultProperty;
import lombok.Getter;
import lombok.Setter;

import javax.validation.constraints.NotBlank;

/**
 * @description： 请求信息
 * @author： 八零后琐话
 * @date： 2023-06-17
 */
@Getter
@Setter
public class InParamData {
    /**
     * 用户名
     */
    @NotBlank
    private String userName;
    /**
     * 年龄
     */
    private Integer age;
    /**
     * 是否新人
     */
    @NotBlank
    private boolean isNew;
}

【OutParamData.java】

package com.busi.monitor.vo;

import lombok.Getter;
import lombok.Setter;

import javax.validation.constraints.NotBlank;

/**
 * @description： 返回信息
 * @author： 八零后琐话
 * @date： 2023-06-17
 */
@Getter
@Setter
public class OutParamData {
    /**
     * 详细信息
     */
    @NotBlank
    private String info;
    /**
     * 校验结果
     */
    private boolean checkResult = false;
}

写在最后

假如说接口请求参数的Header中，要求有token等其他共用参数，我们该如何生成接口文档呢？