# lazy-api-doc

**Repository Path**: qiun/lazy-api-doc

## Basic Information

- **Project Name**: lazy-api-doc
- **Description**: lazy-api-doc是一个专注于生成接口文档的工具，类似于swagger
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2020-05-28
- **Last Updated**: 2021-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 简介

**lazy-api-doc**是一个专注于生成接口文档的工具，类似于swagger。
然而swagger使用起来并不能很好的支持我们接口的侧重点，比喻复杂的响应对象，参数版本...
所以才产生了自己写一个接口工具的想法

- 优点
  - **自动解释复杂响应对象**
  - **支持接口统一响应包装**
  - **参数有版本，接口有版本，接口可从测试版发布到正式版本（记录接口的迭代过程）**
  - **采用JAVA8可重复注解的特性，缩短学习成本**
  - **灵活的参数、响应数据过滤**
  - **支持导出markdown格式的文档，用户可选择gitbook的形式展示接口文档**
  - **同样支持导出到postman调试**
- [接口文档生成](#接口文档生成)
- 注解说明
  - [@Doc](#注解说明)
  - [@IgnoreParameter](#使用ignoreparameter来排除某些不需要的参数)
  - [@RequireParameter](#使用requireparameter来设置某些参数为必须传递的)
  - [@ParameterFilter](#使用parameterfilter来设置必传参数忽略参数仅包含的参数)
  - [@ReturnDoc](#使用returndoc来描述响应的数据)
  - [@ReturnFilter](#使用returnfilter来过滤响应数据)
- [导出POSTMAN调试](#导出postman调试)

# 优点

* 自动解释复杂响应对象
* 支持接口统一响应包装
* 参数有版本，接口有版本，接口可从测试版发布到正式版本（记录接口的迭代过程）
* 采用JAVA8可重复注解的特性，缩短学习成本
* 灵活的参数、响应数据过滤
* 支持导出markdown格式的文档，用户可选择gitbook的形式展示接口文档
* 同样支持导出到postman调试


# 示例

```java
@RestController
@RequestMapping("/order")
@Doc("小程序用户端订单相关") //注解在类上，表示接口分组，不同的类可以用相同的名称来合并接口
@Validated
public interface OrderService {

    @Doc("下单接口") //注解在方法上，表示接口名称
    @PostMapping(value = "/create")
    OrderVo createOrder(OrderDto dto);//接口会自动解释OrderDto类的成员属性为参数

    @Doc(value = "取消订单接口", scope = false) //注解在方法上，表示接口名称 scope=false表示不解释方法中的参数，而直接采用方法上的Doc注解所写的为接口参数
    @Doc(name = "orderId", value = "订单id", required = true)
    @PostMapping(value = "/cancel")
    Boolean cancelOrder(@NotNull(message = "2010000=订单id不能为空") Long orderId);

    @Doc("更换销售接口")
    @Doc(name = "orderId", value = "订单id", required = true) //作为方法中参数的补充 name要于方法中参数名相同
    @Doc(name = "sellerId", value = "销售顾问id", required = true) //作为方法中参数的补充 name要于方法中参数名相同
    @PostMapping(value = "/seller/change/{orderId}")
    @ReturnDoc("true:更换成功 false:更换失败") //对于返回基本类型数据(及其包装类型)的方法作额外补充
    Boolean changeSeller(@PathVariable Long orderId, @NotNull(message = "2010007=销售顾问id不能为空") Long sellerId);

    @Doc("查询订单列表接口")
    @GetMapping(value = "/list/get")
    @ParameterFilter(excludes={"page"}, requires={"size"}) //该注解可以设置必传参数，忽略参数，仅包含的参数 此处是排除PageDto中属性page作为参数，并把属性size设置成必传
    List<OrderListVo> getOrderList(PageDto dto);

    @Doc("查询订单详情接口")
    @GetMapping(value = "/detail/{orderId}")
    @Doc(name = "orderId", value = "订单id", required = true)
    @ReturnFilter(excludes={"creatorId"}) //过滤响应数据OrderDetailVo中的creatorId属性 该注解通常是用来过滤敏感数据
    OrderDetailVo getOrderDetail(@PathVariable Long orderId);

}
```
```java
public class Address implements Serializable {
    
    private static final long serialVersionUID = 78060976917708800L;

    /**
     * 
     * 对应表字段core_address.id
     */
    @Doc(value="", remark="")
    private Long id;

    /**
     * 地点名称
     * 对应表字段core_address.name
     */
    @Doc(value="地点名称", remark="")
    private String name;

    /**
     * 路径代码 暂定备用
     * 对应表字段core_address.path_code
     */
    @Doc(value="路径代码", remark="暂定备用")
    private String pathCode;

    /**
     * 顶级编号
     * 对应表字段core_address.super_id
     */
    @Doc(value="顶级编号", remark="")
    private Long superId;

    /**
     * 上级地点编号
     * 对应表字段core_address.parent_id
     */
    @Doc(value="上级地点编号", remark="")
    private Long parentId;

    /**
     * 详细地址
     * 对应表字段core_address.address
     */
    @Doc(value="详细地址", remark="")
    private String address;

    /**
     * 所有上级编号 逗号隔开
     * 对应表字段core_address.parent_arr
     */
    @Doc(value="所有上级编号", remark="逗号隔开")
    private String parentArr;

    /**
     * 所有上级名称 >号隔开
     * 对应表字段core_address.parent_name_arr
     */
    @Doc(value="所有上级名称", remark=">号隔开")
    private String parentNameArr;

    /**
     * 所有下级编号 逗号隔开 第一个为本级
     * 对应表字段core_address.child_arr
     */
    @Doc(value="所有下级编号", remark="逗号隔开 第一个为本级")
    private String childArr;

    /**
     * 备注
     * 对应表字段core_address.remark
     */
    @Doc(value="备注", remark="")
    private String remark;

    /**
     * 类型 地点所属类型比如1小区、2分区、3楼宇、4单元、5附属之类的
     * 对应表字段core_address.type
     */
    @Doc(value="类型", remark="地点所属类型比如1小区、2分区、3楼宇、4单元、5附属之类的")
    private Integer type;

    @Doc(value = "上级地点", remark = "")
    private com.Address parentAddr;

    @Doc(value = "子级地点", remark = "")
    private List<com.Address> childAddrs;

    /**
     * 层级 parentID为0的是第一级，以此递增
     * 对应表字段core_address.level
     */
    @Doc(value="层级", remark="parentID为0的是第一级，以此递增")
    private Integer level;
}
```
```json
{
    "status": "[int] 调用接口是否成功，0：失败，1：成功",
    "errorCode": "[string] 错误码，当status=0时，必须返回错误码",
    "message": "[string] 错误具体信息",
    "data": [{
        "timeList": [{
            "id": "[long] id",
            "dealerId": "[long] 经销商id",
            "optionalTime": "[string] 试驾可选时间",
            "isChoose": "[int] 是否选择【1=是，0=否】",
            "seq": "[int] 序号",
            "creatorId": "[long] 创建人",
            "creator": "[string] 创建人",
            "createTime": "[date] 创建时间",
            "lastUpdatorId": "[long] 最后更新人",
            "lastUpdator": "[string] 最后更新人",
            "lastUpdateTime": "[date] 最后更新时间",
            "remark": "[string] 备注"
        }],
        "date": "[string] ",
        "time": "[string] ",
        "week": "[string] "
    }]
}
```
![](doc/images/show-api.png)
![](doc/images/test-api.png)

# 接口文档生成

在项目的pom.xml文件中，增加以下内容
```xml
    <properties>
        <!-- 文档管理系统地址 -->
        <doc.host>http://10.201.78.119</doc.host>
        <!-- 接口所属项目名称 -->
        <doc.project>demo</doc.project>
        <!-- 接口响应数据最大解释到第几层 -->
        <doc.maxlevel>4</doc.maxlevel>
        <!-- 扫描指定包下的接口类 -->
        <doc.scan.base>org.basecode.web</doc.scan.base>
        <!-- 响应统一包装类 -->
        <doc.data.rootClass>org.basecode.common.criterion.model.ResultMsg</doc.data.rootClass>
    </properties>

    <!-- 生成接口文档 -->
    <profiles>
        <profile>
            <id>doc</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.codehaus.mojo</groupId>
                        <artifactId>exec-maven-plugin</artifactId>
                        <version>1.6.0</version>
                        <executions>
                            <execution>
                                <phase>install</phase>
                                <goals>
                                    <goal>java</goal>
                                </goals>
                                <configuration>
                                    <mainClass>com.dashu.lazyapidoc.process.CreateApi</mainClass>
                                    <cleanupDaemonThreads>false</cleanupDaemonThreads>
                                    <arguments>
                                        <argument>${doc.host}</argument>
                                        <argument>${doc.project}</argument>
                                        <argument>${doc.maxlevel}</argument>
                                        <argument>${doc.scan.base}</argument>
                                        <argument>${doc.data.rootClass}</argument>
                                    </arguments>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
```
正确填写上述内容后，执行以下命令生成即可
```shell script
mvn clean -Pdoc install
```

# 参数说明

参数名 | 默认 | 参数描述
--- | --- | ---
host | http://127.0.0.1:8567 | 接口管理系统地址 
project | mydemo | 接口所属系统
responseFormatString | [{type}] {chineseName}【{remark}】  | 定义响应数据格式
replaceToNullConfig | \\[\\{type\\}\\] ; \\{chineseName\\} ; 【\\{remark\\}】 | 对返回数据没有格式化到的替换为空，否则格式化符号显示出来不美观
paramsChildBean| true |是否跳过请求时复杂参数的处理 springmvc 对请求参数的类型支持有限
scan |  | 扫描的包名，多个用逗号隔开
rootClass |  | 最外层的包装类（返回数据结构再包一层统一封装）
returnDocParameter | data | 统一包装时，数据填充到统一包装的哪个属性
paramFilter |  | 将参数直接解析为本配置的结果，不再执行代码解析 默认已有：<br/>[{"className":"com.dashu.base.common.model.Token", "params":[{"chineseName":"身份令牌","format":"","name":"token","remark":"","require":"1","type":"string","status":"1"}]},{"className":"org.springframework.web.multipart.MultipartFile", "params":[{"chineseName":"文件","format":"","name":"file","remark":"","require":"1","type":"file","status":"1"}]}] 
maxlevel  | 3 |  返回数据的最大层级数
defaultParserLevel   | 1 |  方法参数解析的默认层级
createFinalField  | false |  bean 解析，是否忽略final修饰的属性
createFieldRemark  | false |  是否对含有子属性的字段生成系统相关的说明
glabPrefix  | data |  全局过滤前缘， 不能为null
rootPath  |  |  项目的根路径 默认与project相同，除非自定义
ignorePath  |  |  忽略的java类路径，多个用逗号隔开，默认已经忽略了Object,javax.servlet
apiType  | springmvc |  生成的接口类型 springmvc dubbo


# 注解说明

## 注解在类上
使用@Doc注解

当@Doc("api权限管理")时，分组名为"api权限管理",描述为空

当@Doc(value = "api权限管理", remark = "这里是描述")

当没有@Doc注解时，分组名为类名
```java
@RestController
@RequestMapping(value="/api_permission")
@Doc("api权限管理")
public interface ApiPermissionService extends GenericBaseService<ApiPermission>{
    ...
}
```
------

## 注解在方法上

### 同样使用@Doc 注解对参数进行说明

@Doc相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
name | 是 | 参数名 | | 当作用于接口参数时，必须<br>当作用于接口时，非必须
value | 否 | 中文名 |  | 参数中文含义<br>当作用于接口时，作为接口标题
remark | 否 | 备注 |  | 说明<br>当作用于接口时，作为接口描述
dataType | 否 | 参数类型 |  |  
example | 否 | 示例 |  | 
defaultValue | 否 | 默认值 |  | 
required | 否 | 是否必须 | false |
ignore | 否 | 是否忽略 | false |
scope | 否 | 作用范围 | true | true：方法中所有参数，包括JAVABEAN <br> false: 仅仅方法上的doc注解 <br>仅在作用于接口时有效


------
### 使用@IgnoreParameter来排除某些不需要的参数

@IgnoreParameter相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 要排除的参数 | | 字符串模式，多个用逗号隔开
ignore | 否 | 要排除的参数 |  | 字符串数组模式

以下三种写法等同
```java
@IgnoreParameter(ignore = {"orderBy", "sord"})
@IgnoreParameter(value = "orderBy,sord")
@IgnoreParameter("orderBy,sord")
```

------
### 使用@RequireParameter来设置某些参数为必须传递的

@RequireParameter相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 必须传的参数 | | 字符串模式，多个用逗号隔开
require | 否 | 必须传的参数 |  | 字符串数组模式
exclude | 否 | 要排除的参数 |  | 字符串数组模式，排除所指定的参数为非必传，其于为必传(**未实现**)

以下三种写法等同
```java
@RequireParameter(require = {"page", "rows"})
@RequireParameter(value = "page,rows")
@RequireParameter("page,rows")
```

------
### 使用@ParameterFilter来设置必传参数，忽略参数，仅包含的参数

@ParameterFilter 集成了@IgnoreParameter 和 @RequireParameter 的功能，另还包括了仅包含指定参数的功能

@ParameterFilter相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 排除某参数 | | 字符串模式，与 excludes作用一样,多个用逗号隔开
includes | 否 | 仅包含所指参数 |  | 字符串数组模式 与excludes互斥
excludes | 否 | 要排除的参数 |  | 字符串数组模式 与includes互斥
requires | 否 | 必须传的参数 |  | 字符串数组模式
unRequires | 否 | 非必传参数 |  | 字符串数组模式 除此之外，其余为必传

------
### 使用@ReturnDoc来描述响应的数据

@ReturnDoc 通常作用于返回基本类型的方法，比如方法返回String Long int boolean等类型时

@ReturnDoc相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 响应数据说明 | | 字符串

------

### 使用@ReturnFilter来过滤响应数据

@ReturnFilter相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 排除某响应字段 | | 字符串模式，与 excludes作用一样,多个用逗号隔开
includes | 否 | 仅包含所指字段 |  | 字符串数组模式 与excludes互斥
excludes | 否 | 要排除的字段 |  | 字符串数组模式 与includes互斥
maxLevel | 否 | 最大层级 | 0 | 
type | 否 | 作用模式 | simple | simple:作用所有同名属性 <br> level:作用指定某层级下的属性
sort | 否 | 排序 | true |  
prefix | 否 | 前缀 |  | 对排除（包含）某属性，指定前缀,仅作用于type=level
ignoreCriterion | 否 | 忽略响应统一包装 | false |　

------
## 注解在JAVABEAN属性上

### 同样使用@Doc 注解对属性进行说明

@Doc相关属性说明

属性 |  是否必须 | 定义 | 默认值 | 说明
--- | --- | --- | --- | ---
value | 否 | 中文名 |  | 参数中文含义
remark | 否 | 备注 |  | 说明
example | 否 | 示例 |  | 
defaultValue | 否 | 默认值 |  | 
required | 否 | 是否必须 | false |
ignore | 否 | 是否忽略 | false | 

# 导出postman调试

1、打开PostMan，点开右上角的设置按钮

![](doc/images/bg1.png)

在弹出的窗口点击“Add”按钮，填写host, protocol的配置后，保存

![](doc/images/bg2.png)

2、导入文档系统的数据， 数据接口地址为：http://10.201.62.26:8567/apiManager/export/testapi/{project}/{treeId}/{name}

示例：http://10.201.62.26:8567/apiManager/export/testapi/mydemo/0/测试系统 

示例：http://10.201.62.26:8567/apiManager/export/testapi/mydemo/0

示例：http://10.201.62.26:8567/apiManager/export/testapi/mydemo

参数：

参数名 |	是否必须 | 	备注
--- | ---- |----
project |	是	| 就是生成文档时所配置的project名称
treeId	| 否	| 接口所属于的分组编号，一般为0，表示该project中所有的接口
name	| 否	| 项目中文名，导出时用来显示，不填则默认为project一样


在POSTMAN导入接口，左上角，点击"Import"按钮，在弹出的窗口中选择“Import From Link”,填写地址之后点击“Import”确定

![](doc/images/bg3.png)

 导入完成后将在左边栏出现所导入的接口

![](doc/images/bg4.png)