= Apigcc示例文档
:doctype: book
:toc: left
:toclevels: 3
:toc-title: 目录
:source-highlighter: highlightjs

[%hardbreaks]
通过javadoc设置文档描述信息
优先级大于通过Environment.description()设置的值


== 文档说明
[%hardbreaks]
所有接口均使用Https调用
/app路径下的接口为app专用
/mini路径下的接口为小程序专用


== 欢迎使用Apiggs

=== 示例接口
请求
[source,HTTP ]
----
GET /greeting?name=apigcc HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+name+|+String+||+apigcc+|+名称+
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "id" : 0,
  "content" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+long+||+0+|+编号+
|+content+|+String+|||+内容+
|===


== 用户模块（标题）
[%hardbreaks]
用户示例模块文字描述（详情）
支持多行文字


=== 用户详情信息
[%hardbreaks]
主动根据id获取用户的信息

请求
[source,HTTP ]
----
GET /users/{id} HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+String+|||+用户编号+
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : {
    "id" : 0,
    "name" : "",
    "age" : 0,
    "createAt" : "",
    "Sex" : ""
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+User+|||
|+data.id+|+int+||+0+|
|+data.name+|+String+|+NotBlank+||
|+data.age+|+Integer+|+Min(1) NotNull+|+0+|
|+data.createAt+|+Date+|||
|+data.Sex+|+String+|+NotBlank+||
|===


=== 用户详情信息（根据email或电话号码）
[%hardbreaks]
多路径适配

请求
[source,HTTP ]
----
GET /users/detail?email=&phone= HTTP/1.1
GET /users/info?email=&phone= HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+email+|+String+|||
|+phone+|+String+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : {
    "id" : 0,
    "name" : "",
    "age" : 0,
    "createAt" : "",
    "Sex" : ""
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+User+|||
|+data.id+|+int+||+0+|
|+data.name+|+String+|+NotBlank+||
|+data.age+|+Integer+|+Min(1) NotNull+|+0+|
|+data.createAt+|+Date+|||
|+data.Sex+|+String+|+NotBlank+||
|===


=== 用户信息新增
请求
[source,HTTP ]
----
POST /users HTTP/1.1
Content-Type: application/json

{
  "id" : 0,
  "name" : "",
  "age" : 0,
  "birthday" : "",
  "tags" : [ "" ],
  "data" : [ ],
  "icons" : [ "" ],
  "attrs" : {
    "" : ""
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+Integer+||+0+|+编号+
|+name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+age+|+int+|+Min(1)+|+0+|+年龄+
|+birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+data+|+List<>+|||
|+icons+|+java.lang.String[]+|||+用户图标+
|+attrs+|+Map<String, String>+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+T+|||
|===


=== 用户信息更新
请求
[source,HTTP ]
----
PATCH /users HTTP/1.1
Content-Type: application/json

{
  "id" : 0,
  "name" : "",
  "age" : 0,
  "birthday" : "",
  "tags" : [ "" ],
  "data" : [ ],
  "icons" : [ "" ],
  "attrs" : {
    "" : ""
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+Integer+||+0+|+编号+
|+name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+age+|+int+|+Min(1)+|+0+|+年龄+
|+birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+data+|+List<>+|||
|+icons+|+java.lang.String[]+|||+用户图标+
|+attrs+|+Map<String, String>+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+T+|||
|===


=== 用户列表信息查询
[%hardbreaks]
默认展示GET方法查询
返回集合类的结果

请求
[source,HTTP ]
----
GET /users/list?page=1&size=20 HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+page+|+int+||+1+|+页码+
|+size+|+int+||+20+|+每页条数+
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : [ {
    "id" : 0,
    "name" : "",
    "age" : 0,
    "createAt" : "",
    "Sex" : ""
  } ]
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+List<User>+|||
|+data.[].id+|+int+||+0+|
|+data.[].name+|+String+|+NotBlank+||
|+data.[].age+|+Integer+|+Min(1) NotNull+|+0+|
|+data.[].createAt+|+Date+|||
|+data.[].Sex+|+String+|+NotBlank+||
|===


=== 用户列表信息搜索
[%hardbreaks]
POST搜索时，请求参数将放在请求体中

请求
[source,HTTP ]
----
POST /users/search HTTP/1.1

q=&page=1&limit=20&totalPage=0&max=0&name=apigcc
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+q+|+String+|||+查询关键字+
|+page+|+int+||+1+|+第几页+
|+limit+|+int+||+20+|+每页条数+
|+totalPage+|+int+||+0+|
|+max+|+int+||+0+|
|+name+|+String+||+apigcc+|+名称+
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : [ {
    "id" : 0,
    "name" : "",
    "age" : 0,
    "createAt" : "",
    "Sex" : ""
  } ]
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+List<User>+|||
|+data.[].id+|+int+||+0+|
|+data.[].name+|+String+|+NotBlank+||
|+data.[].age+|+Integer+|+Min(1) NotNull+|+0+|
|+data.[].createAt+|+Date+|||
|+data.[].Sex+|+String+|+NotBlank+||
|===


=== 用户信息删除
[%hardbreaks]
ResponseEntity、Model以及未知类型将忽略

请求
[source,HTTP ]
----
DELETE /users/{id} HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+String+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+T+|||
|===


=== 用户禁用
[%hardbreaks]
某些项目使用自定义的ArgumentResolver，让spring自动注入一些信息
restdoc在解析时，可通过env.ignoreTypes("UserDtails")来忽略这些

请求
[source,HTTP ]
----
PUT /users/{id}/disable HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+T+|||
|===


=== 查询角色下的用户总数
请求
[source,HTTP ]
----
GET /users/role?role= HTTP/1.1

----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+role+|+Role+|||+枚举类型+
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : 0
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+Integer+||+0+|
|===


=== 批量上传用户信息
请求
[source,HTTP ]
----
POST /users/batch HTTP/1.1
Content-Type: application/json

[ {
  "id" : 0,
  "name" : "",
  "age" : 0,
  "birthday" : "",
  "tags" : [ "" ],
  "data" : [ ],
  "icons" : [ "" ],
  "attrs" : {
    "" : ""
  }
} ]
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+[].id+|+Integer+||+0+|+编号+
|+[].name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+[].age+|+int+|+Min(1)+|+0+|+年龄+
|+[].birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+[].tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+[].data+|+List<>+|||
|+[].icons+|+java.lang.String[]+|||+用户图标+
|+[].attrs+|+Map<String, String>+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "id" : 0,
  "name" : "",
  "age" : 0,
  "birthday" : "",
  "tags" : [ "" ],
  "data" : [ ],
  "icons" : [ "" ],
  "attrs" : {
    "" : ""
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+Integer+||+0+|+编号+
|+name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+age+|+int+|+Min(1)+|+0+|+年龄+
|+birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+data+|+List<>+|||
|+icons+|+java.lang.String[]+|||+用户图标+
|+attrs+|+Map<String, String>+|||
|===


== PageController

=== Hello with ResponseBody
[%hardbreaks]
*********
由于带有@ResponseBody，restdoc将解析该Endpoint
<p>
hhh
\*********
 *********
hhhh
*********
<p>
class ************** {
<p>
}

请求
[source,HTTP ]
----
GET /page/hello HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "id" : 0,
  "content" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+long+||+0+|+编号+
|+content+|+String+|||+内容+
|===


=== 未知的多泛型的tuple 演示
请求
[source,HTTP ]
----
GET /page/tuple HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

[ {
  "id" : 0,
  "name" : "",
  "age" : 0,
  "birthday" : "",
  "tags" : [ "" ],
  "data" : [ ],
  "icons" : [ "" ],
  "attrs" : {
    "" : ""
  }
}, {
  "id" : 0,
  "name" : "",
  "age" : 0,
  "createAt" : "",
  "Sex" : ""
} ]
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+?0.id+|+Integer+||+0+|+编号+
|+?0.name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+?0.age+|+int+|+Min(1)+|+0+|+年龄+
|+?0.birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+?0.tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+?0.data+|+List<>+|||
|+?0.icons+|+java.lang.String[]+|||+用户图标+
|+?0.attrs+|+Map<String, String>+|||
|+?1.id+|+int+||+0+|
|+?1.name+|+String+|+NotBlank+||
|+?1.age+|+Integer+|+Min(1) NotNull+|+0+|
|+?1.createAt+|+Date+|||
|+?1.Sex+|+String+|+NotBlank+||
|===


=== 多个RequestMethod
请求
[source,HTTP ]
----
GET /page/multiMethod HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+T+|||
|===


=== multi
请求
[source,HTTP ]
----
POST /page/multi HTTP/1.1
Content-Type: application/json

{
  "code" : 0,
  "msg" : "",
  "data" : {
    "wrapper" : "",
    "data" : [ {
      "id" : 0,
      "name" : "",
      "age" : 0,
      "birthday" : "",
      "tags" : [ "" ],
      "data" : [ ],
      "icons" : [ "" ],
      "attrs" : {
        "" : ""
      }
    } ]
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+Wrapper<List>+|||
|+data.wrapper+|+String+|||
|+data.data+|+List<UserDTO>+|||
|+data.data.[].id+|+Integer+||+0+|+编号+
|+data.data.[].name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+data.data.[].age+|+int+|+Min(1)+|+0+|+年龄+
|+data.data.[].birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+data.data.[].tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+data.data.[].data+|+List<>+|||
|+data.data.[].icons+|+java.lang.String[]+|||+用户图标+
|+data.data.[].attrs+|+Map<String, String>+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "code" : 0,
  "msg" : "",
  "data" : {
    "wrapper" : "",
    "data" : {
      "id" : 0,
      "name" : "",
      "age" : 0,
      "birthday" : "",
      "tags" : [ "" ],
      "data" : [ ],
      "icons" : [ "" ],
      "attrs" : {
        "" : ""
      }
    }
  }
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+code+|+int+||+0+|+返回码+
|+msg+|+String+|||+返回信息+
|+data+|+Wrapper<UserDTO>+|||
|+data.wrapper+|+String+|||
|+data.data+|+UserDTO+|||
|+data.data.id+|+Integer+||+0+|+编号+
|+data.data.name+|+String+|+Size(min=5,max=20) NotEmpty+||+姓名+
|+data.data.age+|+int+|+Min(1)+|+0+|+年龄+
|+data.data.birthday+|+Date+|+NotNull+||+生日，还是推荐使用javadoc+
|+data.data.tags+|+List<String>+|+Size(min=1,max=2)+||+用户标签+
|+data.data.data+|+List<>+|||
|+data.data.icons+|+java.lang.String[]+|||+用户图标+
|+data.data.attrs+|+Map<String, String>+|||
|===


=== 引用二方Jar
[%hardbreaks]
使用二方Jar的类时，代码解析器无法获取类上的注释，注解
只能获取属性的名称和类型

请求
[source,HTTP ]
----
POST /page/jar HTTP/1.1
Content-Type: application/json

{
  "page" : 0,
  "size" : 0,
  "name" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+page+|+int+||+0+|
|+size+|+int+||+0+|
|+name+|+String+|||
|===

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

{
  "id" : 0,
  "name" : "",
  "man" : ""
}
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+id+|+int+||+0+|
|+name+|+String+|||
|+man+|+String+|||
|===


=== 一个复杂的类型 List<Map<String,User>>
请求
[source,HTTP ]
----
GET /page/map HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

[ {
  "" : {
    "id" : 0,
    "name" : "",
    "age" : 0,
    "createAt" : "",
    "Sex" : ""
  }
} ]
----


=== 一个更复杂的类型 List<Map<String,ResultData<Map<Integer,User>>>>
请求
[source,HTTP ]
----
GET /page/map HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

[ {
  "" : {
    "code" : 0,
    "msg" : "",
    "data" : {
      "0" : {
        "id" : 0,
        "name" : "",
        "age" : 0,
        "createAt" : "",
        "Sex" : ""
      }
    }
  }
} ]
----


=== 一个问号类型 List<Map<String,List<?>>>
请求
[source,HTTP ]
----
GET /page/map HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

[ {
  "" : [ ]
} ]
----


=== 多级菜单
请求
[source,HTTP ]
----
GET /page/menus HTTP/1.1

----

响应
[source,HTTP ]
----
HTTP/1.1 200 OK

[ {
  "id" : 0,
  "name" : ""
} ]
----

[options="header"]
|===
|+名称+|+类型+|+校验+|+默认+|+描述+
|+[].id+|+int+||+0+|
|+[].name+|+String+|||
|+[].menus+|+List<Menu>+|||
|===


== 附录

=== Code
[options=""]
|===
|+OK+|+0+|+ok+
|+ERROR+|+-1+|+error+
|+NoAuth+|+1+|+no auth+
|===


=== StaticFinalCode
[options=""]
|===
|+SUCCESS+|+1+|+成功+
|+ERROR+|+-1+|+失败+
|===


=== 用户角色
[options=""]
|===
|+ADMIN+|+管理员+
|+USER+|+用户+
|+VIP+|+会员+
|===