Java-自动生成带页面可调试的接口文档

介绍：一款java接口文档自动生成的插件，包含了根据接口注释或注解自动生成接口文档，可网页打开。

特点：一款无任何代码侵入的生成方式，10秒钟集成

1.支持读取java默认的行注释和文档注释

2.兼容swagger注释

3.推荐使用内部@ApidocComment注解，属性标注比较全面，默认值也比较友好

4.支持生成接口mock数据

5.支持使用自定义请求参数和请求头真实调用接口测试

6.支持统一添加返回数据外包装

功能列表：

首页-文档介绍

首页-请求环境配置(可配置多个地址，用于模拟请求)

首页-返回参数外包装配置(可手动配置项目对返回数据的包装结构)

首页-同步文档(将文档向指定地址发送同步，目标地址成功接收后会更新自己的文档)

这里是列表文本

这里是列表文本

菜单栏-搜索(可根据接口名称和接口请求路径模糊搜索接口，支持拼音搜索)

菜单栏-控制器列表(controller)

菜单栏-接口列表

菜单栏-删除接口

菜单栏-导入接口(将其他接口文档导入导本地)

接口详情-修改接口基本信息

接口详情-导出接口结构

这里是列表文本

接口详情-选择环境

接口详情-接口返回mock(自动生成假数据)

接口详情-接口真实请求

接口详情-选择参数填写方式(json或form)

接口详情-修改接口入参(字段隐藏，字段必填，字段类型。。。)

接口详情-修改接口返回值

接口详情-导入导出接口入参和返回

包含权限和用户模块，可以自定义用户和访问权限

软件架构

使用springboot-2.1.3核心架构

页面呈现使用VUE

数据存取采用本地json文件

安装说明

下载jar包：https://download.csdn.net/download/qq_37527048/12918433

maven导入项目中，添加配置文件

cn.easyutil

easyapi/artifactId>

使用说明：添加如下配置后，启动项目。

浏览器输入     http://localhost:项目端口/apidoc.html     即可以访问页面

package cn.easyutil.easyapi.logic;

import cn.easyutil.easyapi.config.ApiDocConfiguration;

import org.springframework.context.annotation.Configuration;

//自定义类继承ApiDocStarter

//添加spring配置类注解

//OK,不需要写任何代码，启动项目就完事了

@Configuration

public class ApiInfo extends ApiDocStarter{

@Override

public ApiDocConfiguration start(ApiDocConfiguration configuration) {

//此处为自定义配置，可以返回null，使用默认配置

return null;

}

}

如果想采用自定义配置，可以拉到文章最下面，有详细介绍。

java代码示例(controller层接口)

@Api("客户操作")

@RestController

@RequestMapping("/api")

public class UserController {

@Autowired

private UserService userService;

@ApiOperation("按条件查看自己添加的客户")

@PostMapping("/selfUser")

public List selfUser(UserBean bean){

return userService.listPage(bean);

}

}

java代码示例(实体类)

@Data

public class UserBean {

@ApiModelProperty(value="用户名称",required=true,example="小明")

private String name;

@ApiModelProperty(value="用户手机号码",example="18888888888")

private String mobile;

@ApiModelProperty(value="性别 0:女 1:男",required=true,example="${int}")

private Integer sex;

//用户住址 (easyapi支持java原生注释扫描)

private String address;

/**

* 用户年龄 (easyapi支持java原生注释扫描)

*/

private Integer age;

}

页面样式

可以设置多种环境，进行模拟请求

支持模糊搜索接口路径或名称，支持拼音搜索

接口详情预览

包含：基本信息模块、mock模块、请求参数模块、返回参数模块

说明：任意模块均支持增删改查

接口基本信息详解

接口请求参数设置

接口返回参数设置

mock模块

1.点击发送，将请求到接口基本信息配置中所选择的环境

2.内部使用了session保持，即浏览器与接口文档服务session保持，接口文档服务与请求的环境session保持，间接达到浏览器与请求的环境session保持

3.被禁用的参数不会被发送

4.表格模式和json模式仅是为了方便填写请求参数，实体请求体类型是根据接口基本信息中的请求体类型而决定的。这两种模式填写完成后最终都会转成对应的请求体类型。

5.如果选择的是mock环境，是不会真实请求目标环境的。仅仅是接口文档服务根据返回参数类型随机mock的数据。

还有些详细的功能就不再贴图了，谁用谁知道

个性化配置/自定义配置

默认配置：项目配置文件如果返回空，或没有进行配置，仍然会采用一些默认的配置

1.默认扫描全部controller

2.默认每次启动都会重新扫描，重新扫描只会扫描新增的接口，不会扫描被修改的接口

3.默认每次启动都不会删除旧的构建，即历史接口和修改不会被删除

4.默认文件存储的路径为项目根目录，文件夹名为：项目名 + "-apidoc"

5.默认优先扫描被@ApidocComment注解的文档说明，其次扫描swagger注解的文档相关说明，

再其次扫描java注释的文档相关说明

自定义配置

@Configuration

public class ApiInfo extends ApiDocStarter{

@Override

public ApiDocConfiguration start(ApiDocConfiguration configuration) {

//设置接口文档文件路径

configuration.setApiFilePath("D:/");

//设置接口文档文件夹名称

configuration.setProjectName("easyapi");

//启动时是否重新扫描，有新增的接口会添加

configuration.setRescan(true);

//启动时是否删除旧的构建

configuration.setDelOld(false);

//扫描的包路径，不设置默认扫描整个项目

configuration.setPackageName("cn.easyutil");

//启动时是否自动同步到目标机器

configuration.setSync(true);

//目标机器项目地址

configuration.setSyncAddress("127.0.0.1");

//目标机器项目端口

configuration.setSyncPort(8080);

return configuration;

}

}

自定义高级配置

@Configuration

public class ApiInfo extends ApiDocStarter{

//拦截器都配有默认拦截器，可以通过实现相关filter自主配置拦截器

//也可以通过继承默认拦截器补充个性化配置

@Override

public ApiDocConfiguration start(ApiDocConfiguration configuration) {

//读取参数实体相关信息拦截器

configuration.setReadBeanApiFilter(new DefaultReadBeanApi());

//读取controller相关信息拦截器

configuration.setReadControllerApiFilter(new DefaultReadControllerApi());

//读取接口方法相关信息拦截器

configuration.setReadInterfaceApiFilter(new DefaultReadInterfaceApi());

//读取接口请求参数相关信息拦截器

configuration.setReadRequestParamApiFilter(new DefaultReadRequestParamApi());

//读取接口返回值相关信息拦截器

configuration.setReadResponseParamApiFilter(

new DefaultReadResponseParamApi());

return configuration;

}

}

拦截器配置：ReadBeanApiFilter

介绍：接口文档服务在读取参数类的时候对读取方式和结果进行拦截和配置。例如

1.类字段的隐藏属性读取方式和依据

2.类字段的必填属性读取方式和依据

3.类字段的字段说明属性读取方式和依据

4.类字段的mock属性读取方式和依据

5.类字段的忽略属性读取方式和依据

... ...

其他拦截器的详细方法和作用就不再一一列举了，还是那句话，谁用谁知道

技术探讨qq：547595531