# IPoker-SmartApi

**Repository Path**: heckerstone/IPoker-SmartApi

## Basic Information

- **Project Name**: IPoker-SmartApi
- **Description**: Api 工具项目
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2020-03-13
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IPoker-SmartApi

#### 介绍
Api 工具项目 零浸入


### 使用方法

#### 1、引入工具包
```
<dependency>
    <groupId>cn.ipokerface</groupId>
    <artifactId>smart-api</artifactId>
    <version>${latest-version}</version>
</dependency>
```

#### 2、设置环境开始使用
```


# 构建CoreContext
CoreContext context = CoreContext.builder()
                .filePath("smart-api.md")               # 文件位置
                .packageName("cn.ipokerface.demotest")  # 需要扫描的包目录
                .type(new MarkdownFormatter())          # 输入文件类型
                .build();
                
# 生成文档
Generator.generate(context);
```

#### 3、具体注解
```
@ApiDefine(name="", value="")
# 此注解用于定义变量,可以重复使用
# name 变量名称
# value 变量值

@ApiEnum(name = "数据状态", key = "State", value = {
            @ApiEnumValue(name = "暂存", key = "STASH"),
            @ApiEnumValue(name = "正常", key = "COMMON"),
            @ApiEnumValue(name = "删除", key = "DELETE")
    })
# 定义枚举值
# name 枚举名字
# key 枚举key ，可在参数中引用
# ApiEnumValue.key 枚举常量
# ApiEnumValue.name 枚举描述



@ApiGroup(id = 3, name = "第三组")
@ApiGroup(id = 4, name = "1.1", group = 1)
# 用来定义接口的分组分级
# id 分组id, 输出文档中可用于排序 
# name 分组名字
# group 分级ID 可构建多级树


@ApiPrefix(value="") 
# 可以在一个类中定义所有接口的前缀 , 此类中所有api共用


@Api(url = "/login/wechat", name = "微信登录", method = Method.POST, response = ResponseType.Json, group = 2)
# 定义一个接口  一个方法只能使用一个注解
# url 接口的链接   prefix + url
# name 接口名字
# method 接口的请求方法
# response 返回数据类型 默认为json
# group 所属分组id


@ApiHeader(key = "Content-Type", name = "请求类型", options = "Content-Type")
# 必须使用在Api注解同一方法
# key Header的key
# name Header 的描述
# options 可取值引入 为一个枚举值的key



@ApiParameter(key = "user",name = "用户信息",required = true,type = Type.Model,define = "userModel",propertyOf="user", remark="", options="")
# 请求参数, 必须用在api同一方法   可以重复使用
# key     参数的key
# name    参数的名字
# required 参数是否必填
# type      参数类型 {@link Type}
# define   可以为Type为 Model 或者 ModelList 的参数定义一个名字  
# propertyOf 为参数定义属性 ，值为参数 的define
# remark  参数详细说明
# options 可以为参数引入枚举值的key


@ApiResponse(key = "user",name = "用户信息",contains = true,type = Type.Model,define = "userModel",propertyOf="user", remark="")
# 请求参数, 必须用在api同一方法   可以重复使用
# key     返回值的key
# name    返回值的名字
# required 返回值是否必含
# type      返回值类型 {@link Type}
# define   可以为Type为 Model 或者 ModelList 的参数定义一个名字  
# propertyOf 为参数定义属性 ，值为参数 的define
# remark  参数详细说明
# options 可以为参数引入枚举值的key


@ApiPrefix("/api/user")
@RestController
@RequestMapping("/api/user")
public class UserController {


    @Api(url = "/login/wechat", name = "微信登录", method = Method.POST, response = ResponseType.Json, group = 2)
    @ApiHeader(key = "Content-Type", name = "请求类型", options = "Content-Type")
    @ApiHeader(key = "Token", name = "用户凭证")
    @ApiParameter(key = "user",
            name = "用户信息",
            required = true,
            type = Type.Model,
            define = "userModel")
    @ApiParameter(key = "username",
            name = "用户名",
            required = true,
            type = Type.String,
            propertyOf = "userModel")
    @ApiParameter(key = "usersss",
            name = "用户",
            required = true,
            type = Type.Model,
            propertyOf = "userModel",
            define = "usersss")
    @ApiParameter(key = "userdddd",
            name = "用户ddd",
            required = true,
            type = Type.String,
            propertyOf = "usersss")
    @ApiResponse(key = "status", name = "状态", type = Type.String, contains = true)
    @ApiResponse(key = "body", name = "数据", type = Type.Model, contains = true)
    @ApiResponse(key = "username", name = "用户名", type = Type.String, contains = true, propertyOf = "body")
    @RequestMapping(value = "/aaa", method = RequestMethod.POST)
    public Object add(){


        return new Object();
    }
}

```


### 自定义文档成生器

```
# 1、自定义Parser 继承 cn.ipokerface.api.AbstractParser

# 2、自定义Formatter 继承 cn.ipokerface.api.Formatter
# 并在getParser方法中返回自定义的parser
public class MarkdownFormatter implements Formatter {


    @Override
    public AbstractParser getParser() {
        return new MarkdownParser();
    }
}


# 3、 引入自定义的formatter
CoreContext context = CoreContext.builder()
                .filePath("smart-api.md")               # 文件位置
                .packageName("cn.ipokerface.demotest")  # 需要扫描的包目录
                .type(new MarkdownFormatter())          # 输入文件类型
                .build();

```