# esayDoc

**Repository Path**: bai8li/esay-doc

## Basic Information

- **Project Name**: esayDoc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-29
- **Last Updated**: 2021-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

**Documentation**  

doc地址:<a herf="https://gitee.com/bai8li/esay-doc">https://gitee.com/bai8li/esay-doc </a>

#### EsayDoc文档使用
 1.生成api接口文档列表，和服务文档列表

2.配合mzh/validate 验证器可自动根据验证规则、场景生成文档所需参数

3.无需手动编写doc文档一键生成导出postman,eolinker等文档

---

#### 1.开始使用
```
安装文档
composer require leebai/hyperf-esaydoc  
 
发布配置文件
php bin/hyperf.php vendor:publish leebai/hyperf-esaydoc

默开启文档web访问，如需关闭，在 config/autoload/doc.php 将enable设为false

```
---

#### 2.主要注解说明
 Api :标注api接口说明  
 Service :服务接口  
 Responses :返回参数  
 Params :入参属性,输出字段
 
 ---
 
#### 3.访问生成的文档 
 ```

访问 http://youdDomain/doc

```

 
*******
 
#### 4文档详情概述

**所有配置请到config/autoload/doc.php修改，已标注好**  


**4.1 api列表功能**

1.自动生成登录配置，即可以保存token到postman模拟登录的真实场景    
 
2.自动根据接口是否需要登录添加token到header头进行鉴权  

3.根据是否是列表自动添加currantPage(当前页),row(每页条数)  

4.自动根据请求方法生成query，或者form-data 参数体，并根据默认值填入对应的值，可直接进行请求  

**4.2 服务列表功能**

1.生成服务对应的入参，返回值列表对应的参数  

2.根据是否是列表自动添加currantPage(当前页),row(每页条数)  

#### 5注解参数详解  
```
...

/**
 * @AutoController
 * @Api(name="测试管理" ,needLogin=false)
 */
class TestController
{
    /**
     *
     * @ApiOperation(name="测试登录",d›esc="这是一个测试登录的接口",needLogin=true,method="GET")
     * @Params(type="1" ,params={
     *     @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
     * })
     * @Responses(isList=false,data={
     *      @Param(name="userName",type="string",desc="用户名",required=true,default="254497767")},
     *      failStatus={@FailResponse(status="2",message="普通错误")})
     */
    public function index()
    {
    ...

```

Api|标注在类上面|描述该类是属于什么模块
---|--|---
name|如:用户模块,商品模块|描述该模块功能的名字
needLogin|true/false |描述该模块是否需要登录  

``` 
示例: @Api(name="测试管理" ,needLogin=false)

```

------

ApiOperation|标注在方法上|描述方法具体操作
---|--|---
name| 如:登录，注册 |描述该接口功能的名字
desc| 如:后台管理员登录，新用户前台注册 |描述该接口功能的详情描述
method| GET/POST/PUT/DELETE |描述该模块请求方法,如与hyperf冲突，hyperf优先
needLogin| true/false |描述该接口是否需要登录,与Api冲突,此处优先 

```

示例: @ApiOperation(name="测试登录",d›esc="这是一个测试登录的接口",needLogin=true,method="GET")

```
---

Service|标注在类上面|描述该接口是属于什么服务模块
---|--|---
name|如:用户模块服务,商品模块服务|描述该服务模块功能的名字
```

示例: @Service(name="用户服务模块")


```

---

ServiceOpeation|标注在服务接口的方法上|描述方法具体操作
---|--|---
name| 如:添加用户，编辑用户信息 |该服务接口的名字
desc| 如:后台管理员添加用户，后台编辑用户信息 |服务接口的详情描述

```

示例: @ServiceOpeation(name="添加用户",desc="添加管理员用户")

```

---

Params|标注在方法上|描述该方法参数体
---|--|---
type| 请求参数(0,默认)/响应参数(1)/header头(2) |描述该参数体的类型
params|  |所有参数Param的数组集合

```
示例: @Params(params={
     *     @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
     * })

```

---

Param|标注在Params内部|具体的参数内心
---|--|---
name| 如:username,email,passworld |请求的参数名
required| true/false |该参数是否为必填
default| 如:john john@mallae.com 123456 |该参数的默认值
type| string/number/file |该参数类型
desc| 如:用户名，邮箱，密码| 该参数的具体描述

```

示例: @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),

```
---

Responses|标注在方法上|描述该方法或者服务的返回参数
---|--|---
status| 返回对应的状态码，如:0,100,400 |成功返回状态码(配置文件配置)
message| 如:ok |成功返回消息
isList| true/false | 返回的是否是列表,生成对应的page信息
data| |所有响应Param的数组集合
failStatus|如:{status:302,message:请先登录},{status:300,message:权限不足} |错误状态列表

```

示例: * @Responses(isList=false,data={
     *      @Param(name="userName",type="string",desc="用户名",required=true,default="254497767"),
     *     failStatus={
     *          @FailResponse(status="2",message="普通错误"),
     *          @FailResponse(status="3",message="不是普通错误"),
     *     }
     *   )

```

---

FailResponse|标注Responses内部的failStatus里|可多个，描述对应的错误状态
---|--|---
status| 如:300，302 |状态码
message| 如:请先登录，权限加班 |错误消息

```
示例: @FailResponse(status="2",message="普通错误"),

```

#### 实际使用截图
  
 **接口配置**
 ![hyperf 注解文档生成](https://mallae-im.oss-cn-chengdu.aliyuncs.com/%E6%88%AA%E5%B1%8F2021-04-30%2009.57.28.png)
 
 **postman示例**
 ![hyperf 注解文档生成](https://mallae-im.oss-cn-chengdu.aliyuncs.com/%E6%88%AA%E5%B1%8F2021-04-30%2010.16.03.png)