代替swagger，Git拉去代码解析注释生成文档，gorgeous-doc华丽的文档

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访问，不做多讲。

这里页面后面还会进行优化

1. 修改接口类型（post,get,put,delete）
2. 修改接口访问路径
3. 添加请求参数
4. 添加临时访问接口

 

• 菜单四个功能，API搜索、切换、更新、设置

1. 搜索：class名称、class描述、API描述、API后段方法名称、API接口路径
2. 切换：上面以及写了，这里是全局参数修改会刷新页面
3. 更新：从新拉去分支代码解析文档
4. 设置：项目、环境、注释配置

• 设置

项目管理、环境配置都是基本的增删改，重点说说配置管理，上传类

1. 配置管理

配置管理主要是解析注释注解用，类型分注释五个、注解三个。这里有一个优先级注解》注释》默认注释

注释 【@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文件下的类全部加载和当前项目一起解析

• 优点很明显，不需要额外的注解，项目也不用依赖什么包
• 缺点也需要说一下

1. 开发时必须要提交代码到服务器才能这边才能拉去解析
2. 对多模块项目还有问题
3. 支持的项目目前只支持git svn还不支持
4. 只能解析springmvcAPI注解

缺点这里会在后面慢慢完善，开发环境在调用接口时允许修改请求方式、接口路径、接口参数，支持添加接口。多模块留了口子后面再补上。3、4看后面的使用情况吧

 

我认为这种方式还是很不错的，项目不需要集成生成API的技术更专注于业务，完成也有一段时间了在测试简化发布，欢迎大家来使用，也欢迎有兴趣的同学一起来完善

 

最后说一下gorgeous-doc这个名字真的超超超合适，优雅华丽的解决API文档问题，谢谢起名字的邓同志