聊聊JSON Schema

javascript/jquery

浏览数:495

2019-3-12

简介

json现在已经成为比较通用灵活的数据交换格式,尤其是在web方面,总是少不了它的身影,js原生就支持它。网页中与服务器中和服务器交换信息也基本上式基于json的。

在现在的开发中,特别是在前后端分离的开发中,后端提供接口,前端通过接口拿取数据;

那么有一个问题来了,那就是该如何描述接口,可能有人说好办,通过接口文档,那么,文档如何维护呢,完全手写么?在这个自动化的时代,这样也太耗神费力了吧!当然不排除很多人是这么干的。

另外,如何体现字段规则,如字段长度,字段是否必填等验证规则,以及返回的字段有些什么东西,我想在文档里面不好体现这些吧。即使在文档中体现了,万一有些改动呢,有些事就不好办了。

关于如何描述json数据,我想没有什么能比json schema更合适了的吧;已成一个规范专门维护,还有一系列的配套工具,前端的后端的都有,比较好的接口文档工具Swagger就是基于它的。那么啰嗦了那么多,让我们来看看如何粗略的描述下json数据吧。

描述

JSON Schema本身就是
JSON格式,自己描述自己,它们俩之间的关系可以理解为类与对象的关系,也可以理解为集合与元素的关系,或
JSON Schema描述
JSON数据的模式,怎么样好理解就怎么理解

数字

{
  "type": "number"
}

这样就可以把值描述成数字了
需要加个标题,我们只要加上title属性就好了

{
  "type": "number",
  "title": "字段1"
}

一般数字有最大值和最小值,我们可以加上maximumminimum

{
  "type": "number",
  "maximum": 10,
  "minimum": 1
}

需要一个默认值,加上default即可

值得注意的是
title, description, default是通用的

null

{
  "type": null
}

字符串

{
  "type": "string"
}

当字符串需要符合某种格式的时候,加上format

{
  "type": "string",
  "format": "url"
}

或者使用pattern,里面是正则表达式

{
  "type": "string",
  "pattern": "\\d+"
}

长度通过maxLengthminLength来描述

布尔值

{
  "type": "boolean"
}

对象

对象描述算是比较复杂的,不过也比较明了,通过properties来描述每个字段,每个字段的描述也是一个JSON Schema,也就是可以不断的嵌套

下面描述一个对象,拥有属性aabb,分别是数字和字符串

{
  "type": "object",
  "properties": {
    "aa": {
      "type": "number"
    },
    "bb": {
      "type": "string"
    }
  }
}

当某些字段必填的时候,加上required,是一个数组,里面是必填的字段

{
  "type": "object",
  "properties": {
    "aa": {
      "type": "number"
    },
    "bb": {
      "type": "string"
    }
  },
  "required": ["aa"]
}

除上面给出的以外,还能定义属性的个数;以及属性是动态的时候,可以定义属性满足的规则;另外还能定义依赖,也就是当某个字段提供的时候,相应的字段也必须提供

数组

{
  "type": "array"
}

maxItems,minItems为数字,定义数组有多长
uniqueItems为布尔值,定义是否有重复值
定义数组每一项满足的格式,加上items; 可以为对象,为一个JSON Schema或是一个对象数组,每个位置都为一个JSON Schema,描述对应位置的数据格式

以上只是JSON Schema的简略描述,冰上一角,更多的东西可以在官网找到,它的强大超乎你的想象,后续我还会介绍相应的工具,包括不仅限于

  • 根据代码自动生成文档
  • 校验
  • 表单生成
  • 通过代码生成JSON Schema
  • 自动化测试

另外欢迎光临个人小站,http://yuanxiaowa.github.io/,一些小工具望大家喜欢。