web接口参数校验神器-json schema 快速入门

Json Schema 快速入门

JSON 模式是一种基于 JSON 格式定义 JSON 数据结构的规范。它被写在 IETF 草案下并于 2011 年到期。JSON 模式：

  • 描述现有数据格式。
  • 干净的人类和机器可读的文档。
  • 完整的结构验证，有利于自动化测试。
  • 完整的结构验证，可用于验证客户端提交的数据。

Json schema 格式

Json schema 本身遵循Json规范，本身就是一个Json字符串，先来看一个例子

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

我们来看一下json schema 最外层包含以下几个字段

$schema 描述 示例
$schema $schema 关键字状态，表示这个模式与 v4 规范草案书写一致。  
title 标题，用来描述结构  
description 描述  
type 类型 .
properties 定义属性  
required 必需属性

上面只是一个简单的例子，从上面可以看出Json schema 本身是一个JSON字符串，由通过key-value的形式进行标示。
type 和 properties 用来定义json 属性的类型。required 是对Object字段的必段性进行约束。事实上,json Schema定义了json所支持的类型，每种类型都有0-N种约束方式。下一节我们来，细致介绍一下。

Json schema 类型

Object

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

object类型有三个关键字:type（限定类型）,properties(定义object的各个字段),required（限定必需字段）,如下：
| 关键字 | 描述 | 示例 |
|:------------- |:---------------| ----- |
| type |类型|. |
| properties |定义属性||
| required|必需属性||
| maxProperties |最大属性个数||
| minProperties |最小属性个数||
| additionalProperties |true or false or object|参考|
properties 定义每个属性的名字和类型，方式如上例。

array

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "array",
    "items": {
        "type": "string"
     },
     "minItems": 1,
     "uniqueItems": true
    }

array有三个单独的属性:items,minItems,uniqueItems:

关键字 描述 示例
items array 每个元素的类型 .
minItems 约束属性，数组最小的元素个数  
maxItems 约束属性，数组最大的元素个数  
uniqueItems 约束属性，每个元素都不相同  
additionalProperties 约束items的类型，不建议使用 示例
Dependencies 属性依赖 用法
patternProperties   用法

string

{
   "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "object",
    "properties": {
        "ip": {
            "mail": "string",
            "pattern":"w+([-+.]w+)*@w+([-.]w+)*.w+([-.]w+)*"
        },
        "host": {
            "type": "phoneNumber",
            "pattern":"((d{3,4})|d{3,4}-)?d{7,8}(-d{3})*"
        },
    },
    "required": ["ip", "host"]
}

　　

关键字 描述 示例
maxLength 定义字符串的最大长度，>=0 .
minLength 定义字符串的最小长度，>=0  
pattern 用正则表达式约束字符串

integer

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "object",
    "properties": {
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

number

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme‘s catalog",
    "type": "object",
    "properties": {
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

| 关键字      | 描述  |    示例   |
|:------------- |:---------------| ----- |
| minimum |最小值|. |
| exclusiveMinimum |如果存在 "exclusiveMinimum" 并且具有布尔值 true，如果它严格意义上大于 "minimum" 的值则实例有效。||
| maximum |约束属性，最大值||
| exclusiveMaximum |如果存在 "exclusiveMinimum" 并且具有布尔值 true，如果它严格意义上小于 "maximum" 的值则实例有效。||
| multipleOf |是某数的倍数，必须大于0的整数||

number 关键字可以描述任意长度，任意小数点的数字。number类型的约束有以下几个：

关键字 描述 示例
minimum 最小值 .
exclusiveMinimum 如果存在 "exclusiveMinimum" 并且具有布尔值 true，如果它严格意义上大于 "minimum" 的值则实例有效。  
maximum 约束属性，最大值  
exclusiveMaximum 如果存在 "exclusiveMinimum" 并且具有布尔值 true，如果它严格意义上小于 "maximum" 的值则实例有效。

boolean

{
"type": "object",
"properties": {
"number": { "type": "boolean" },
"street_name": { "type": "string" },
"street_type": { "type": "string",
"enum": ["Street", "Avenue", "Boulevard"]
}
}
}

true or false

enum

{
  "type": "object",
  "properties": {
    "number":      { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "type": "string",
                     "enum": ["Street", "Avenue", "Boulevard"]
                   }
  }
}

也可以这么做

{
  "type": "object",
  "properties": {
    "number":      { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": ["Street", "Avenue", "Boulevard"]
  }
}

null

进阶

了解了上面的各个类型的定义及约定条件，就可以满足大部分情况了。但为了写出更好的json schema,我们再学习几个关键字

$ref

$ref 用来引用其它schema,
示例如下：

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product set",
    "type": "array",
    "items": {
        "title": "Product",
        "type": "object",
        "properties": {
            "id": {
                "description": "The unique identifier for a product",
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "price": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true
            },
            "tags": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "minItems": 1,
                "uniqueItems": true
            },
            "dimensions": {
                "type": "object",
                "properties": {
                    "length": {"type": "number"},
                    "width": {"type": "number"},
                    "height": {"type": "number"}
                },
                "required": ["length", "width", "height"]
            },
            "warehouseLocation": {
                "description": "Coordinates of the warehouse with the product",
                "$ref": "http://json-schema.org/geo"
            }
        },
        "required": ["id", "name", "price"]
    }
}

definitions

当一个schema写的很大的时候，可能需要创建内部结构体，再使用$ref进行引用，示列如下：

{
    "type": "array",
    "items": { "$ref": "#/definitions/positiveInteger" },
    "definitions": {
        "positiveInteger": {
            "type": "integer",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    }
}

allOf

意思是展示全部属性，建议用requires替代

不建议使用，示例如下

{
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "allOf": [
    { "$ref": "#/definitions/address" },
    { "properties": {
        "type": { "enum": [ "residential", "business" ] }
      }
    }
  ]
}

anyOf

意思是展示任意属性，建议用requires替代和minProperties替代，示例如下：

{
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}

oneOf

其中之一

{
  "oneOf": [
    { "type": "number", "multipleOf": 5 },
    { "type": "number", "multipleOf": 3 }
  ]
}

not

非 * 类型
示例

{ "not": { "type": "string" } }

原文地址：https://www.cnblogs.com/lianhaifeng/p/11886451.html

时间： 2024-10-07 14:19:25

web接口参数校验神器-json schema 快速入门的相关文章

SpringBoot实现通用的接口参数校验

本文介绍基于Spring Boot和JDK8编写一个AOP,结合自定义注解实现通用的接口参数校验. 缘由 目前参数校验常用的方法是在实体类上添加注解,但对于不同的方法,所应用的校验规则也是不一样的,例如有一个AccountVO实体: publicclassAccountVO{privateStringname;//姓名privateIntegerage;//年龄} 假设存在这样一个业务:用户注册时需要填写姓名和年龄,用户登陆时只需要填写姓名就可以了.那么把校验规则加在实体类上显然就不合适了. 所

接口参数校验之@Valid与BindingResult

接口方法往往需要对入参做一些校验,从而判断入参是否合格,而javax.validation包为我们提供了一些常用的参数校验注解,使用起来很方便. 下面这个示例是检验入参对象中的password是否为空 1. 创建一个User.java import javax.validation.constraints.NotBlank; public class User { private String username; @NotBlank private String password; privat

夺命雷公狗---微信开发54----微信js-sdk接口开发（1）之快速入门

js-sdk基本介绍 除去服务号的九大接口外,微信提供了JS-SDK接口,所谓JS-SDK接口也就是在网页中使用javascript来更改网页设置, (比如隐藏右上角的菜单)获取用户状态(比如地理位置)甚至调用微信的录音功能上传下载和扫描等功能, 由于需要用到JS代码,因此该接口只能在开发模式下使用. 我们还是照老规矩,先查看手册 JS-SDK快速入门体验案例: 我们来实现一个简单的小功能,通过js-sdk接口,灵活的控制右上角菜单的显示和隐藏 我们先来看看手册: 我们将上一节课的dream.p

论文神器Latex30分钟快速入门教程-只需9步向学神看齐

小E说:工欲善其事,必先利其器.立志做个安静的美学霸的你,学会Latex,一定能使你的论文写作事半功倍. 1.LaTeX软件的安装和使用 方法A(自助):在MikTeX的官网下载免费的MikTeX编译包并安装.下载WinEdt(收费)或TexMaker(免费)等编辑界面软件并安装. 方法B(打包):在ctex.org下载ctex套装(含MikTeX及WinEdt) 哈哈这一部分当然不包含在标题的30分钟里. 2.第一个文档 打开WinEdt,建立一个新文档,将以下内容复制进入文档中,保存,保存类

Spring Boot 参数校验

1.背景介绍 开发过程中,后台的参数校验是必不可少的,所以经常会看到类似下面这样的代码 这样写并没有什么错,还挺工整的,只是看起来不是很优雅而已. 接下来,用Validation来改写这段 2.Spring Boot文档中的Validation 在Spring Boot的官网中,关于Validation只是简单的提了一句,如下 其实,Spring Validator和Hibernate Validator是两套Validator,可以混着用,这里我们用Hibernate Validator 3.

PCB WCF Web接口增减参数后,在客户端不更新的情况，是否影响客户端,评估测试

1.目的:由于接口众多,服务端变更接口,会造成服务停用更新,造成客户端不能使用或报错, 在此评估[Web中心]此服务端,接口接口参数增加或减少,是否对客户端造成影响 2.评估内容:服务端增加单值参数,服务端减少单个值参数,Mod对象增加参数,Mod对象减少参数, (而Json数据类型在此不作评估内容,是因为Json对象反序列化具有很好的伸缩型,不会影响客户端调用方) 3.附PCB工程系统集成示意图: 一.Web服务端增加单个值参数 改前-- 服务端(1个参数): /// <summary> /

json schema校验

工作中使用到了json schema格式校验的问题,在网上查了些资料,结合自己的理解记录一下. json schema可以对json结果字符串做出一些约束,例如: 1. 值类型是:array, object, number, string等等 2.值类型必须是枚举中的一个 3. 字符串的长度限制 4. 对字符串判断是否符合正则表达式 5. array元素个数 6. object对象必要属性 测试schema文件 1 { 2 "$schema": "http://json-sc

快速入门web接口自动化测试---知识与思想准备阶段（一）

刚换了工作,老板要求我搞接口自动化,可是之前完全没有搞过,怎么办?怎么办?答:先把B装下了,然后学!个人感觉,这是在工作提升自己的最好方式,嘻嘻,鄙人在这里以日记的形式,记录自己作为一个技术渣,点点滴滴开展接口自动化的过程. 首先很惭愧,大学里的知识框架落下了太多的空白,第一步,要填补自己在知识框架的空白. 对,先来一份知识清单: HTTP协议: 请求头,请求参数,Get ,Post, Put , Delete , 重定向,资源(括号后面接一万字) 接口的概念: web接口与程序接口 常用的接口

JSON解析器之json schema校验及代码实现

项目有个业务需要对JSON格式的数据校验,需要一些必要字段的验证,实现一个JSON解析器.所以学习了json schema的语法和解析器的实现. 本篇是先说通用的JSON验证,也就是json schema和在java代码中的校验使用. json schema是什么 json schema实际上就是一个JSON文件,文件内容是对JSON数据的结构及内容的约束,就像是xml文件的xsd文件对xml的验证. 先看一下简单的schema内容 1 { 2 "$schema": "htt