优化 文档生成功能

java110

2022-09-17 0abd0924f29af225ec3d90d7ad63f9560f9846dc

优化 文档生成功能

 java110-doc/readme.md

New file
@@ -0,0 +1,150 @@
## java110 api 文档使用说明

### @Java110ApiDoc 的使用

样例

```
@Java110ApiDoc(
        title = "HC小区管理系统api接口文档",
        description = "HC小区管理系统api接口文档",
        company="Java110工作室",
        version = "v1.4"
)
```
title 表示 接口文档题目

description 表示 接口文档说明

company 文档公司

version 文档版本

该注解用在入口 类 比如 Hc api 的restApi.java 中

### @Java110RequestMappingsDoc 和 @Java110RequestMappingDoc 的使用

```
@Java110RequestMappingsDoc(
        mappingsDocs = {
                @Java110RequestMappingDoc(name="用户中心",resource = "user",url="http://service-user/userDoc",seq = 1),
                @Java110RequestMappingDoc(name="账户中心",resource = "acct",url="http://service-acct/acctDoc",seq = 2),
                @Java110RequestMappingDoc(name="通用中心",resource = "common",url="http://service-common/commonDoc",seq = 3),
                @Java110RequestMappingDoc(name="小区中心",resource = "community",url="http://service-community/communityDoc",seq = 4),
                @Java110RequestMappingDoc(name="开发中心",resource = "dev",url="http://service-dev/devDoc",seq = 5),
                @Java110RequestMappingDoc(name="费用中心",resource = "fee",url="http://service-fee/feeDoc",seq = 6),
                @Java110RequestMappingDoc(name="定时任务",resource = "job",url="http://service-job/jobDoc",seq = 7),
                @Java110RequestMappingDoc(name="oa",resource = "oa",url="http://service-oa/oaDoc",seq = 8),
                @Java110RequestMappingDoc(name="订单中心",resource = "order",url="http://service-order/orderDoc",seq = 9),
                @Java110RequestMappingDoc(name="报表中心",resource = "report",url="http://service-report/reportDoc",seq = 10),
                @Java110RequestMappingDoc(name="商户中心",resource = "store",url="http://service-store/storeDoc",seq = 11),
        }
)
```

资源目录映射 注解

name 为 名称 文档中的菜单

resource 为资源目录

url 为微服务地址

seq 文档中的排序

### Java110CmdDoc

接口注解

```
@Java110CmdDoc(title = "用户登录",
        description="登录功能 主要用于 员工 或者管理员登录使用",
        httpMethod="post",
        url="/app/login.pcUserLogin",
        resource = "user",
        author = "吴学文"
)
```

作用在cmd文件上注解 描述 接口信息

title 接口名称

description 接口描述

httpMethod 接口类型

url 接口请求地址

resource 资源路径，要写 @Java110RequestMappingDoc 下resource

author 作者信息

### @Java110ParamsDoc 
请求参数注解

```
@Java110ParamsDoc(params = {
        @Java110ParamDoc(name = "username", length = 30, remark = "用户名，物业系统分配"),
        @Java110ParamDoc(name = "passwd", length = 30, remark = "密码，物业系统分配"),
})
```
描述请求参数信息

parentNodeName 上级节点名称

name 当前节点名称

type 类型 String  int  Object Array 

length 类型为 string时 的长度 

defaultValue 默认值;

remark 说明;

### @Java110ResponseDoc

返回参数注解
```
@Java110ResponseDoc(
        params = {
                @Java110ParamDoc(name = "code", type = "int", length = 11, defaultValue = "0", remark = "返回编号，0 成功 其他失败"),
                @Java110ParamDoc(name = "msg", type = "String", length = 250, defaultValue = "成功", remark = "描述"),
                @Java110ParamDoc(name = "data", type = "Object", remark = "有效数据"),
                @Java110ParamDoc(parentNodeName = "data",name = "userId", type = "String", remark = "用户ID"),
                @Java110ParamDoc(parentNodeName = "data",name = "token", type = "String", remark = "临时票据"),
        }
)

```

描述返回参数信息

parentNodeName 上级节点名称

name 当前节点名称

type 类型 String  int  Object Array

length 类型为 string时 的长度

defaultValue 默认值;

remark 说明;

### @Java110ExampleDoc

举例节点

```
@Java110ExampleDoc(
        reqBody="{'username':'wuxw','passwd':'admin'}",
        resBody="{'code':0,'msg':'成功','data':{'userId':'123123','token':'123213'}}"
)
```

reqBody 请求报文

resBody 返回报文


 java110-doc/src/main/java/com/java110/doc/annotation/Java110ParamsDoc.java

@@ -9,7 +9,13 @@
@Retention(RetentionPolicy.RUNTIME)
public @interface Java110ParamsDoc {

    Java110HeaderDoc[] headers() default @Java110HeaderDoc(name = "");
    Java110HeaderDoc[] headers() default {
            @Java110HeaderDoc(name="APP-ID",defaultValue = "通过dev账户分配应用",description = "应用APP-ID"),
            @Java110HeaderDoc(name="TRANSACTION-ID",defaultValue = "uuid",description = "交易流水号"),
            @Java110HeaderDoc(name="REQ-TIME",defaultValue = "20220917120915",description = "请求时间 YYYYMMDDhhmmss"),
            @Java110HeaderDoc(name="JAVA110-LANG",defaultValue = "zh-cn",description = "语言中文"),
            @Java110HeaderDoc(name="USER-ID",defaultValue = "-1",description = "调用用户ID 一般写-1"),
    };

    Java110ParamDoc[] params() default @Java110ParamDoc(name = "");


 java110-doc/src/main/java/com/java110/doc/annotation/Java110RequestMappingDoc.java

@@ -13,6 +13,8 @@

    String resource() ;

    int seq() default 1;

    String url();

    String startWay() default "cloud";

 service-api/src/main/java/com/java110/api/rest/RestApi.java

@@ -41,17 +41,17 @@

@Java110RequestMappingsDoc(
        mappingsDocs = {
                @Java110RequestMappingDoc(name="账户中心",resource = "acct",url="http://service-acct/acctDoc"),
                @Java110RequestMappingDoc(name="通用中心",resource = "common",url="http://service-common/commonDoc"),
                @Java110RequestMappingDoc(name="小区中心",resource = "community",url="http://service-community/communityDoc"),
                @Java110RequestMappingDoc(name="开发中心",resource = "dev",url="http://service-dev/devDoc"),
                @Java110RequestMappingDoc(name="费用中心",resource = "fee",url="http://service-fee/feeDoc"),
                @Java110RequestMappingDoc(name="定时任务",resource = "job",url="http://service-job/jobDoc"),
                @Java110RequestMappingDoc(name="oa",resource = "oa",url="http://service-oa/oaDoc"),
                @Java110RequestMappingDoc(name="订单中心",resource = "order",url="http://service-order/orderDoc"),
                @Java110RequestMappingDoc(name="报表中心",resource = "report",url="http://service-report/reportDoc"),
                @Java110RequestMappingDoc(name="商户中心",resource = "store",url="http://service-store/storeDoc"),
                @Java110RequestMappingDoc(name="用户中心",resource = "user",url="http://service-user/userDoc"),
                @Java110RequestMappingDoc(name="用户中心",resource = "user",url="http://service-user/userDoc",seq = 1),
                @Java110RequestMappingDoc(name="账户中心",resource = "acct",url="http://service-acct/acctDoc",seq = 2),
                @Java110RequestMappingDoc(name="通用中心",resource = "common",url="http://service-common/commonDoc",seq = 3),
                @Java110RequestMappingDoc(name="小区中心",resource = "community",url="http://service-community/communityDoc",seq = 4),
                @Java110RequestMappingDoc(name="开发中心",resource = "dev",url="http://service-dev/devDoc",seq = 5),
                @Java110RequestMappingDoc(name="费用中心",resource = "fee",url="http://service-fee/feeDoc",seq = 6),
                @Java110RequestMappingDoc(name="定时任务",resource = "job",url="http://service-job/jobDoc",seq = 7),
                @Java110RequestMappingDoc(name="oa",resource = "oa",url="http://service-oa/oaDoc",seq = 8),
                @Java110RequestMappingDoc(name="订单中心",resource = "order",url="http://service-order/orderDoc",seq = 9),
                @Java110RequestMappingDoc(name="报表中心",resource = "report",url="http://service-report/reportDoc",seq = 10),
                @Java110RequestMappingDoc(name="商户中心",resource = "store",url="http://service-store/storeDoc",seq = 11),
        }
)
public class RestApi extends BaseController {

 service-user/src/main/java/com/java110/user/cmd/login/PcUserLoginCmd.java

@@ -7,6 +7,8 @@
import com.java110.core.event.cmd.CmdEvent;
import com.java110.core.factory.AuthenticationFactory;
import com.java110.core.factory.GenerateCodeFactory;
import com.java110.core.log.LoggerFactory;
import com.java110.doc.annotation.*;
import com.java110.dto.store.StoreUserDto;
import com.java110.dto.user.UserDto;
import com.java110.dto.userLogin.UserLoginDto;
@@ -22,19 +24,46 @@
import com.java110.utils.util.BeanConvertUtil;
import com.java110.utils.util.DateUtil;
import org.slf4j.Logger;
import com.java110.core.log.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

import java.text.ParseException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * 保存编码映射处理类
 * 用户登录 功能
 * 请求地址为/app/login.pcUserLogin
 */

@Java110CmdDoc(title = "用户登录",
        description = "登录功能 主要用于 员工 或者管理员登录使用",
        httpMethod = "post",
        url = "/app/login.pcUserLogin",
        resource = "user",
        author = "吴学文"
)

@Java110ParamsDoc(params = {
        @Java110ParamDoc(name = "username", length = 30, remark = "用户名，物业系统分配"),
        @Java110ParamDoc(name = "passwd", length = 30, remark = "密码，物业系统分配"),
})

@Java110ResponseDoc(
        params = {
                @Java110ParamDoc(name = "code", type = "int", length = 11, defaultValue = "0", remark = "返回编号，0 成功 其他失败"),
                @Java110ParamDoc(name = "msg", type = "String", length = 250, defaultValue = "成功", remark = "描述"),
                @Java110ParamDoc(name = "data", type = "Object", remark = "有效数据"),
                @Java110ParamDoc(parentNodeName = "data",name = "userId", type = "String", remark = "用户ID"),
                @Java110ParamDoc(parentNodeName = "data",name = "token", type = "String", remark = "临时票据"),
        }
)

@Java110ExampleDoc(
        reqBody="{'username':'wuxw','passwd':'admin'}",
        resBody="{'code':0,'msg':'成功','data':{'userId':'123123','token':'123213'}}"
)
@Java110Cmd(serviceCode = "login.pcUserLogin")
public class PcUserLoginCmd extends Cmd {
    private final static Logger logger = LoggerFactory.getLogger(PcUserLoginCmd.class);