Git地址:https://gitee.com/lanyanhua/gorgeous-doc
演示地址:http://47.100.15.244/gorgeous/docs
联系方式:qq:3092575337、wx:lanyanhua1024、email:lanyanhua1024@163.com
特点:
通过git拉去项目文件进行解析注释注解生成API文档
零侵入,无需任何配置,独立运行,注释生成文档,支持读取swagger注解,自定义注释配置,在线调试
无损替换:
项目已引用swagger注解包,可以读取swagger注释
支持自定义注释读取,使用特定注释读取项目也可以无损替换
发布版:具体安装方式请打开码云地址
https://gitee.com/lanyanhua/gorgeous-doc/releases/2.0
开始使用
- 添加项目
git地址、分支拉去代码用,上下文路径、端口配合环境信息调用接口
点击保存,需要等待一会。这里需要去拉去git上的代码
- 添加环境
环境是调用接口的配置,headerKey:ajax请求携带的header的key值在切换时进行修改
接口访问地址:【域名】+【项目端口】+【项目上下文】+【API的路径】
例子:【http://localhost】:【5160】/【gorgeous】/【project/listProjectAll】
切换:切换项目、分支、环境以及配置headkey的值
-
在线接口调试
原理就是ajax访问,不做多讲。
这里页面后面还会进行优化
- 修改接口类型(post,get,put,delete)
- 修改接口访问路径
- 添加请求参数
- 添加临时访问接口
- 菜单四个功能,API搜索、切换、更新、设置
- 搜索:class名称、class描述、API描述、API后段方法名称、API接口路径
- 切换:上面以及写了,这里是全局参数修改会刷新页面
- 更新:从新拉去分支代码解析文档
- 设置:项目、环境、注释配置
- 设置
项目管理、环境配置都是基本的增删改,重点说说配置管理,上传类
- 配置管理
配置管理主要是解析注释注解用,类型分注释五个、注解三个。这里有一个优先级注解》注释》默认注释
注释 【@Description:】 classTag methodTag methodParamTag methodReturnTag fieldTag 注解 【@Api(tags)】 classAnnotation methodAnnotation fieldAnnotation
下面是默认注释读取、自定义注释读取、注解读取解析原理(这块是核心能不能解析到想要的注释注解都是这个,看完不太理解的加联系方式滴滴我)
默认注释读取
class
/**
* {{类名称}}
* @author: lanyanhua
* @date: 2020/12/4 8:38 下午
*/
public class ProjectController {
}
方法
/**
* {{方法名称}}
* @param {{参数名称}} {{参数描述}}
* @return {{返回值描述}}
*/
public BaseResponse<Integer> addProject(@RequestBody ProjectAddVo vo) {
}
字段
/**
* {{字段描述}}
*/
private String name;
自定义注释注解
注释类型
classTag
methodTag
methodParamTag
methodReturnTag
fieldTag
注解类型
classAnnotation
methodAnnotation
fieldAnnotation
配置方式
注释 classTag @Description:
/**
* @author: lanyanhua
* @date: 2020/12/20 10:21 下午
* @Description: {{自定义注释值}}
*/
注解 classAnnotation @Api(tags) "tags"注解取值字段
@Api(tags = "{{自定义注解值}}", produces = MediaType.APPLICATION_JSON_VALUE)
@Api源码
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Api {
String value() default "";
String[] tags() default {""};
...
}
这是页面
- 上传类
最后是一个功能,为啥要上传类呢?因为我这里解析的是源码,你那些在jar包中的类我是莫有的所以啊你得把这个类上传
看看页面,文件、包路径。这里需要注意类的路径千万不能错错了就解析不到
例子:
下面是类,文件就选这个类的文件就好了,包路径【com/github/pagehelper】。有注意到吗,这个类和包源码其实是不一样的,可以随便改哦
package com.github.pagehelper;
import java.util.List;
/**
* 分页信息
*/
public class PageInfo<T> {
/**
* 当前页
*/
private int pageNum;
/**
* 每页的数量
*/
private int pageSize;
/**
* 当前页的数量
*/
private int size;
/**
* 总页数
*/
private int pages;
/**
* 总行数
*/
protected long total;
/**
* 数据
*/
protected List<T> list;
}
这里多提一嘴,这个文件上传的位置。要是你以及下载安装好了那么可以看到目录下有一个repository文件夹这个文件加是存放拉去代码的仓库,再看下面有一个public文件夹这个文件夹这里就是文件上传的位置,在解析代码时我会把这个public文件下的类全部加载和当前项目一起解析
- 优点很明显,不需要额外的注解,项目也不用依赖什么包
- 缺点也需要说一下
- 开发时必须要提交代码到服务器才能这边才能拉去解析
- 对多模块项目还有问题
- 支持的项目目前只支持git svn还不支持
- 只能解析springmvcAPI注解
缺点这里会在后面慢慢完善,开发环境在调用接口时允许修改请求方式、接口路径、接口参数,支持添加接口。多模块留了口子后面再补上。3、4看后面的使用情况吧
我认为这种方式还是很不错的,项目不需要集成生成API的技术更专注于业务,完成也有一段时间了在测试简化发布,欢迎大家来使用,也欢迎有兴趣的同学一起来完善
最后说一下gorgeous-doc这个名字真的超超超合适,优雅华丽的解决API文档问题,谢谢起名字的邓同志