前言

Github:https://github.com/HealerJean

博客:http://blog.healerjean.com

1、多点

1.1、查询排重接口

接口详情  
地址 http://www.baidu.com (正式环境)
请求方式 GET
参数 是否必填 说明
idfa 广告标识符,只支持单个查询
source 渠道来源,具体值在接入时再进行分配

返回结果 格式 JSON
状态码 10000 success(调用成功)
  10001 param error(参数错误)
  10002 query failed(查询失败)
  10010 access prohibited(访问拒绝)

具体返回结果举例:

1、查询成功

{
  "state": 10000,
  "message": "success",
  "data": {
    "BD239708-2874-417C-8292-7E335A537FAD": 1 //已经存在
  }
}

{
  "state": 10000,
  "message": "success",
  "data": {
    "BD239708-2874-417C-8292-7E335A537FAD": 0 //不存在
  }
}
  1. 接口调用失败
{
  "state": 10010,
  "message": "access prohibited",
  "data": [
    
  ]
}

2、小米

2.1、角色列表查询

说明

  • 测试调用地址:/api/roles
  • 调用方式:GET

请求参数

参数名称 参数类型 参数长度 是否必需 说明 备注
pageSize 整数   每页显示数量 默认10
pageNo 整数   当前查看页码 默认1
roleName 字符串 64 角色名称  
systemCode 字符串 32 系统CODE  
isPage 布尔 4 是否分页 true/false

请求报文样例

{
    "pageSize": 1,
    "pageNo": 1,
    "roleName": "",
    "systemCode": "scf-manager",
    "isPage": true
}

响应参数

参数名称 参数类型 参数长度 是否必需 说明 备注
msg 字符串 255 返回结果  
total 数字   总数  
pageNo 数字   页数  
totalPage 数字   总页数  
pageSize 数字   每页数量  
datas Role数组   返回的数据信息  

Role 数据结构

参数名称 参数类型 参数长度 是否必需 说明 备注
id 数字 16 id  
roleName 字符串 64 角色名称  
systemCode 字符串 64 系统CODE  
status 字符串 8 状态  
desc 字符串 255 描述  

响应报文样例

{
    "msg": "角色列表查询成功",
    "total": 2,
    "pageNo": 1,
    "totalPage": 1,
    "datas": [
        {
            "id": 1,
            "roleName": "后台管理员",
            "systemCode": "scf-manager",
            "status": "10"
        },
        {
            "id": 4,
            "roleName": "测试角色哦",
            "systemCode": "scf-manager",
            "status": "10",
            "desc": "真的是测试"
        }
    ],
    "pageSize": 10
}

返回码解析

返回码 含义 备注
200 成功  

2.2、代码生成markdown

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface FieldName {
    String value();
}
package com.healerjean.proj.util.markdown;


import com.healerjean.proj.dto.Demo.DemoDTO;
import org.hibernate.validator.constraints.Length;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;
import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;


public class JsonToMarkDownTable {

    private static final String TABLE_HEAD = "|  参数名称  | 参数类型 | 参数长度 | 是否必需 |      说明      |    备注     |\n";
    private static final String TABLE_HEAD_DIVIDING_LINE = "| :--------: | :------: | :------: | :------: | :----------: | :---------: |\n";
    private static final String TITLE = "## 接口名称\n> **说明**\n- 调用地址:URL\n- 调用方式:***METHOD***\n> **请求参数**\n\n";
    private static final String REQUEST_EXAMPLE = "    \n> **请求报文样例**\n\n```\n\n```\n";
    private static final String RESPONSE_PARAMS = "> **响应参数**\n\n\n";
    private static final String RESPONSE_EXAMPLE = "   \n> **响应报文样例**\n\n```\n\n```\n";
    private static final String RESPONSE_CODE = "> **返回码解析**\n\n| 返回码 |含义| 备注 |\n| :----: | :----------------: | :--: |\n|  200 |成功||\n";


    public static void main(String[] args) {
        // System.out.println(interMarkdown(DemoDTO.class, DemoDTO.class));
        // System.out.println(interMarkdown(DemoDTO.class, null));
        System.out.println(interTable(DemoDTO.class));
    }


    /**
     * 制作markdown接口
     *
     * @param requestClass
     * @param responseClass
     * @return
     */
    public static String interMarkdown(Class requestClass, Class responseClass) {
        StringBuilder res = new StringBuilder();
        res.append(TITLE);

        //请求参数
        if (requestClass != null) {
            res.append(TABLE_HEAD);
            res.append(TABLE_HEAD_DIVIDING_LINE);
            String requestTable = table(requestClass);
            res.append(requestTable);
        }
        res.append(REQUEST_EXAMPLE);


        //返回参数
        res.append(RESPONSE_PARAMS);
        res.append(TABLE_HEAD);
        res.append(TABLE_HEAD_DIVIDING_LINE);
        if (responseClass != null) {
            String responseTable = table(responseClass);
            res.append(responseTable);
        }
        res.append("| msg | 字符串 |255| 是| 返回结果 | \n   \n");
        res.append(RESPONSE_EXAMPLE);



        //返回Code
        res.append(RESPONSE_CODE);
        return res.toString();
    }


    public static String interTable(Class clazz) {
        StringBuilder res = new StringBuilder();
        res.append(TABLE_HEAD);
        res.append(TABLE_HEAD_DIVIDING_LINE);
        String requestTable = table(clazz);
        res.append(requestTable);
        return res.toString();
    }


    /**
     * 获取所有字段名
     */
    public static Set<Field> getField(Class c) {
        Set<Field> declaredFields = new HashSet<>();
        Class tempClass = c;
        //反射获取父类里面的属性
        while (tempClass != null && !tempClass.getName().toLowerCase().equals("java.lang.object")) {
            declaredFields.addAll(Arrays.asList(tempClass.getDeclaredFields()));
            tempClass = tempClass.getSuperclass();
        }
        return declaredFields;
    }

    public static String table(Class clazz) {
        StringBuilder table = new StringBuilder();
        Set<Field> requestFields = getField(clazz);
        for (Field field : requestFields) {
            field.setAccessible(true);
            String fieldType = field.getGenericType().toString();
            //1、参数名称
            table.append("| " + field.getName());
            //2、参数类型
            switch (fieldType) {
                case "class java.lang.Integer":
                case "class java.lang.Long":
                case "class java.math.BigDecimal":
                    table.append("|数字");
                    break;
                case "class java.time.LocalDate":
                case "class java.time.LocalDateTime":
                    table.append("|日期");
                    break;
                case "class java.lang.String":
                    table.append("|字符串");
                    break;
                default:
                    if (fieldType.startsWith("java.util.List")) {
                        table.append("|集合 ");
                    } else if (fieldType.startsWith("class com.")) {
                        table.append("|对象 ");
                    } else if (fieldType.startsWith("java.util.List<com.")) {
                        table.append("|对象集合 ");
                    }
                    break;
            }


            if (field.getAnnotations() != null && field.getAnnotations().length > 0) {
                //3、参数长度
                if (field.isAnnotationPresent(Length.class)) {
                    Length length = field.getAnnotation(Length.class);
                    table.append("|  " + length.max() + "   ");
                } else {
                    table.append("|         ");
                }


                //4、是否必填
                if ((field.isAnnotationPresent(NotBlank.class)) || (field.isAnnotationPresent(NotEmpty.class)) || (field.isAnnotationPresent(NotNull.class))) {
                    table.append("|是");
                } else {
                    table.append("|否");
                }

                //5、说明
                if (field.isAnnotationPresent(FieldName.class)) {
                    FieldName fieldName = field.getAnnotation(FieldName.class);
                    table.append("|  " + fieldName.value() + " |      |\n");
                } else {
                    table.append("|         |      |  \n");
                }
            } else {
                //参数长度,是否必填
                table.append("|      |否   ");
                //说明,备注
                table.append("|         |      |  \n");
            }
        }

        return table.toString();
    }


}



3、个人Swagger规范


@Api(description = "系统管理-字典维护")
@RestController
@RequestMapping("iku/sys")
@Slf4j
public class DictionaryController extends BaseController {

    @Autowired
    private DictionaryService dictionaryService;

    @ApiOperation(value = "字典类型查询",
                  notes = "字典类型查询",
                  consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
                  produces = MediaType.APPLICATION_JSON_UTF8_VALUE,
                  response = DictionaryTypeDTO.class
                 )
    @GetMapping(value = "dictType/{id}", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public ResponseBean getDictType(@PathVariable Long id) {
        log.info("系统管理-字典管理--------字典类型查询--------字典类型Id:{}", id);
        if (id == null) {
            throw new ParameterErrorException("字典类型Id不能为null");
        }
        DictionaryTypeDTO typeDTO = new DictionaryTypeDTO();
        typeDTO.setId(id);
        return ResponseBean.buildSuccess("字典类型查询成功", dictionaryService.queryDictionaryTypeSingle(typeDTO));
    }




@RestController
@RequestMapping("iku")
@Api(description = "商品管理")
@Slf4j
public class ItemController extends BaseController {

    @Autowired
    private ItemGoodService itemGoodService;


    @ApiOperation(value = "通过商品链接查找商品",
                  notes = "通过商品链接查找商品",
                  consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE,
                  produces = MediaType.APPLICATION_JSON_UTF8_VALUE,
                  response = ItemGoodDTO.class
                 )
    @GetMapping(value = "item/detail", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
    public ResponseBean itemDetail(ItemGoodDTO itemGoodDTO) {
        log.info("商品管理--------通过商品链接查找商品--------请求参数:{}", itemGoodDTO);
        String validate = ValidateUtils.validate(itemGoodDTO, ValidateGroup.ItemDetail.class);
        if (!CommonConstants.COMMON_SUCCESS.equals(validate)) {
            throw new ParameterErrorException(validate);
        }
        LoginUserDTO adminUser = UserUtils.getLoginUser();
        itemGoodDTO = itemGoodService.itemDetail(itemGoodDTO, adminUser);
        return ResponseBean.buildSuccess(itemGoodDTO);
    }


ContactAuthor