Apifox 实体类转请求参数数据模型

Posted 2023-01-24 笑虾

Apifox 数据模型

• form-data 请求参数
• • 请求参数格式 CSV
  • 1. 手动处理
  • 2. 辅助脚本
• 数据模型
• • 界面位置
  • 数据模型格式 JSON Schema
  • JS：JavaDoc 转【数据模型】
  • • 生成 JSON Schema 示例
• 两种格式互相转换
• • JSON 转 CSV
  • CSV 转 JSON
• 参考资料
• • Idea 实体类生成 JavaDoc

form-data 请求参数

我们在JavaBean中已经写好了注释，怎么快速的导进 Apifox ？利用批量编辑功能。

请求参数格式 CSV

接口管理》接口》请求参考》Body》form-data》批量编辑。
支持逗号模式、冒号模式。自己对比 一下就知道区别了。以下是逗号模式

格式：参数名,类型,必填,示例值,说明

参数名	类型	必填	示例值	说明
字段名1	string	true	666	巴拉巴拉
字段名2	string	true	777	巴拉巴拉

接下来要做的就是把Java中的实体类，转成这种格式了。

1. 手动处理

复制实体类代码到Notepad++先清理一下注释，然后放到Excel中调整下列序。就可以直接复制到Apifox的批量编辑了。

0. 删除所有 // ========================== xxxxx ==========================
   查找: ^\\s+//.*[\\n\\r]+
   替换: 空

1. 删除【 /**】
   查找: ^\\s+/\\*\\*[\\n\\r]\\s+\\*\\s
   替换: 空

2. 删除【 * 】
   查找: [\\n\\r]\\s+\\*\\s
   替换: |

3. 删除【 */】
   查找: [\\n\\r]\\s+\\*/[\\n\\r]\\s+
   替换: ,

2. 辅助脚本

先将实体类导出 JavaDoc 再用以下 js 提取参数

var fields = [...document.querySelectorAll(`a[name="field.detail"]~ul>li`)];
// 数据模型 JSON Schema 模板
var template = [];

function getType(str)
    return str.substring(str.lastIndexOf('.') + 1, str.lastIndexOf(' '))


var csv = fields.map( field => 
    // 格式：参数名,类型,必填,示例值,说明
    var 参数名 = field.querySelector('h4').innerText;
    var 类型 = getType(field.querySelector('pre').innerText);
    var 说明 = field.querySelector('div')?.innerText;
    return `$参数名,$类型,true,,$说明`;

).join('\\n');

console.log(csv);
copy(csv);

数据模型

创建了数据模型可以重复使用。

界面位置

数据模型格式 JSON Schema

数据模板格式如下，因为Apifox暂时还不支持 JSON5 所以免费送个正则用来删除注释/\\*\\s.*\\s\\*/

/* 数据模型 JSON Schema */

    "type": "object", 							/* 根节点 */
    "properties": 
        "username": 							/* 字段名 */
            "title": "用户名",					/* 字段名-中文名 */
            "type": "string"                    /* 字段名-字段类型 */
        ,
        "pwd": 
            "title": "密码", "type": "string"
        ,
        "code": 
            "title": "业务编码",
            "type": [ "string", "null" ],		/* string类型，并且可为空 */
            "minLength": 1,						/* 字段-更多：最小长度 */
            "maxLength": 10,					/* 字段-更多：最大长度 */
            "format": "date",					/* 字段-更多：格式化日期 */
            "default": "66666666",				/* 字段-更多：默认值 */
			"pattern": "\\\\d+",					/* 字段-更多：正则校验 */
			"description": "这是字段的说明部分",	/* 字段-说明*/
			"mock":  "mock": "@regexp(/\\\\w3,5\\\\d+/)" 
        ,
        "dict": 								/* 字段名 */
            "title": "字典",
            "type": [ "array", "null" ],		/* 这个字典是array类型，有子元素 items */
            "items": 							/* 就是一个嵌套的 Object */
                "type": "object",
                "properties": 
                    "value":  "title": "值", "type": "string" ,
                    "label":  "title": "名称", "type": "string" 
                ,
                "x-apifox-orders": [ "label", "value" ],
                "required": [ "label", "value" ]
            
        
    ,
    "required": [ "username", "pwd", "dict" ],
    "x-apifox-orders": [ "code", "username", "pwd", "dict" ]

JS：JavaDoc 转【数据模型】

var fields = [...document.querySelectorAll(`a[name="field.detail"]~ul>li`)];
// 数据模型 JSON Schema 模板
var template = 
    "type": "object",
    "properties": ,
    "required": [],
    "x-apifox-orders": []


function getType(str)
    return str.substring(str.lastIndexOf('.') + 1, str.lastIndexOf(' '))


var JsonSchema = fields.reduce(( t, field ) => 
    var fieldName = field.querySelector('h4').innerText;
    var type = field.querySelector('pre').innerText;
    var txtArr = field.querySelector('div')?.innerText.split(' ');
	// 取得字段名
    t.properties[fieldName] = 
        // 取得字段类型
        "type" : getType(field.querySelector('pre')?.innerText),
        // 取得中文名（注释第一行）
        "title": txtArr.shift(),
        // 取得说明（注释其余行）
        "description" : txtArr.join('\\n')
    

    // 必填项（默认全都必填）
    t.required.push(fieldName);
    //【数据模型】中字段显示顺序
    t[`x-apifox-orders`].push(fieldName);
    return t;
, template);

console.log(JsonSchema);
copy(JsonSchema);

生成 JSON Schema 示例

  "type": "object",
  "properties": 
    "author": "title": "作者", "type": "String",
    "content": "title": "诗词内容", "type": "String",
    "createTime": "title": "创建时间", "type": "Date",
    "id": "title": "主键", "type": "Long",
    "serialVersionUID": "type": "private static long",
    "title": "title": "诗词标题", "type": "String",
    "updateTime": "title": "更新时间", "type": "Date"
  ,
  "required": ["author", "content", "createTime", "id", "serialVersionUID", "title", "updateTime"],
  "x-apifox-orders": ["author", "content", "createTime", "id", "serialVersionUID", "title", "updateTime"]

两种格式互相转换

JSON 转 CSV

实现json参数转CSV参数。官方竟然没自带这东西，

function JsonSchema2CSV(JsonSchema)
    var prop = JsonSchema.properties;
    var fields = JsonSchema[`x-apifox-orders`]; // 这里要注意排序数组才有全字段。必填数组不一定。
    var csv = fields.map(field => 
        return `$field,$prop[field].type,true,,$prop[field].description.replaceAll('\\n',' ')`;
    );
    return csv.join('\\n');


console.log(JsonSchema2CSV(JsonSchema));
copy(JsonSchema2CSV(JsonSchema));

CSV 转 JSON

function csv2Json(csv)
    // 数据模型 JSON Schema 模板
    var template = "type":"object", "properties":, "required":[], "x-apifox-orders":[];

    return csv.split('\\n').reduce(( t, field ) => 
        // 格式：[参数名, 类型, 必填, 示例值, 说明]
        var [name, type, requiredField, ,...txtArr] = field.split(/,| /);
        // 取得字段名
        t.properties[name] = 
            // 取得字段类型
            "type" : type,
            // 取得中文名（说明的第一部分）
            "title": txtArr.shift(),
            // 取得说明（说明的其余部分）
            "description" : txtArr.join('\\n')
        

        // 必填项（默认全都必填）
        if(requiredField=== "true" )
            t.required.push(name);
        
        //【数据模型】中字段显示顺序
        t[`x-apifox-orders`].push(name);
        return t;
    , template);


console.log(csv2Json(csv));
copy(csv2Json(csv));

参考资料

Idea 实体类生成 JavaDoc

Tools >> Generate JavaDoc

1. 根据需要选择自己要生成的部分。可以加选几个文件，也可以选择范围。
2. 输出的位置 。
3. 实体中的字段都是私有的，所以这里调整到 private
4. 保持勾选。
   4.1. 正常来说文档中字段概要自动按首字母排序。
   4.2. 字段详细资料下的字段顺序与实体类保持一致，但我取消@deprecated，就会导致也排序。不明觉厉
5. 设置言语 Locale：zh_CN
6. 命令行参数（设置字符集）Other command line arguuments：-encoding UTF-8 -charset UTF-8