本文地址:使用 Json Schema 定义 API

前面我们介绍了 Json Schema 的基本内容,这篇文章我们结合 jsonschema2pojo 工具深入分析如何使用 Json Schema 生成 API,学习更多关于 Json Schema 的关键字等知识。

jsonschema2pojo 该库提供了多种使用Json Schame文件生成 Java 类的方法,比如 Maven插件, Gradle插件, Ant任务, 以及直接使用命令行,甚至还可以在代码中直接使用,具体参照 jsonschema2pojo Getting Started

这里我直接采用 Mac 命令行的方式,在 Mac 下安装此命令的方式比较简单,直接运行 brew install jsonschema2pojo 安装即可。

properties

在一个类中,最关键的就是属性了,每个类都可能有多个属性,在 Json Schema 中就是通过 properties 来定义类的属性的, properties 中的每个条目都是所定义类的一个属性。

比如,对于此 Json Schema MyObject.json

{
"type" : "object",
"properties" : {
"foo" : {
"type" : "string"
}
}
}

我们执行 jsonschema2pojo 任务后,可以生成对应的 Java 类:

public class MyObject {
private String foo;
public String getFoo() {
return foo;
}
public void setFoo(String foo) {
this.foo = foo;
}
}

type

像我们 Java 中有多种类型,那不同的类型在 Json Schema 中如何表示呢?一般通用的转换如下所示,这也是 jsonschema2pojo 工具默认使用的转换方式:

Schema Type | Java Type

:-: | :-:

string | java.lang.String

number | java.lang.Double

integer| java.lang.Integer

boolean| java.lang.Boolean

object | 自己生成的类

array | java.util.List

array(with “uniqueItems”:true)|java.util.Set

null | java.lang.object

any | java.lang.object

值的注意的是,如果我们增加了 usePrimitives 选项,对于 Integer, Double, Boolean 这三个包装类将会转换成基本类型 int, double, boolean

additionalProperties

我们平时开发中,为了类利于扩展,有时会给类增加一个Map类型的属性,这样当外部需要传更多的参数给我们时,不需要更改API,直接将参数放到这个 Map 里就可以快速实现。jsonschema2pojo同样也实现了这个功能,当我们没有指定additionalProperties属性为false或者没有指定additionalProperties属性时,jsonschema2pojo会为我们定义的类自动生成一个类型为MapadditionalProperties属性。

比如:

{
"type" : "object"
}

或者

{
"type" : "object",
"additionalProperties" : {}
}

生成的类:

public class MyObject {
private java.util.Map<String, Object> additionalProperties = new java.util.HashMap<String, Object>(); @org.codehaus.jackson.annotate.JsonAnyGetter
public java.util.Map<String, Object> getAdditionalProperties() {
return this.additionalProperties;
} @org.codehaus.jackson.annotate.JsonAnySetter
public void setAdditionalProperties(String name, Object value) {
this.additionalProperties.put(name, value);
}
}

items

items 用于指定我们定义 List 以及 Set 类型时的子元素详情,比如子元素的类型以及描述等。

例如:

{
"type" : "object",
"properties" : {
"myArrayProperty" : {
"type" : "array",
"items" : {
"type" : "string"
}
}
}
}

生成的属性:

List<String> myArrayProperty;

required

如果一个属性在required中指定了,那么这个属性会有一个 Required 的注解,表明该属性是必需的。

uniqueItems

这个就是我们上面表格中的用于区分 ListSet 的关键字了,如果我们定义的array中声明uniqueItemstrue,那么最终转换为的属性的类型就为Set

enum

对于枚举类型的定义需要使用到此关键字,比如:

{
"type" : "object",
"properties" : {
"myEnum" : {
"type" : "string",
"enum" : ["one", "secondOne", "3rd one"]
}
}
}

生成的枚举类:

@Generated("com.googlecode.jsonschema2pojo")
public static enum MyEnum { ONE("one"),
SECOND_ONE("secondOne"),
_3_RD_ONE("3rd one");
private final String value; private MyEnum(String value) {
this.value = value;
} @JsonValue
@Override
public String toString() {
return this.value;
} @JsonCreator
public static MyObject.MyEnum fromValue(String value) {
for (MyObject.MyEnum c: MyObject.MyEnum.values()) {
if (c.value.equals(value)) {
return c;
}
}
throw new IllegalArgumentException(value);
}
}

default

如果我们需要某个属性有默认值,可以加上此参数,生成类的属性会自动实例化。具体可参照下表:

Json Schema | Java

:-: | :-:

myString : { “type”:“string”, “default”:“abc”} | myString : { “type”:“string”, “default”:“abc”};

myInteger : { “type”:“integer”, “default”:“100”} | private Integer myInteger = 100;

myNumber : { “type”:“number”, “default”:“10.3”}|private Double myNumber = 10.3D;

myMillis : { “type”:“string”, “format”:“utc-millisec”, “default”:“500”}|private Long myMillis = 500L;

myDate : { “type”:“string”, “format”:“date-time”, “default”:“500”}|private Date myDate = new Date(500L);

myDate : { “type”:“string”, “format”:“date-time”, “default”:“2011-02-24T09:25:23.112+0000”}|private Date myDate = new Date(1298539523112L);

myList : { “type”:“array”, “default”:[“a”,“b”,“c”]}|private List myList = new ArrayList(Arrays.asList(“a”,“b”,“c”));

title && description

titledescription 用于描述一个属性,当我们指定了这两个参数时,jsonschema2pojo

会在属性的上面生成 Java 文档,并且titledescription之上。

format

formatjsonschema2pojo 提供给我们扩展更多类型的一个参数,在上面介绍的type中可以看到我们生成的 Java 类型并不多,像 Date 等这些参数都没有,但是当我们加上 jsonschema2pojo能识别的format参数后,就可以扩展我们的属性类型,具体参照:

Format value | Java Type

:-: | :-:

“date-time” | java.util.Date

“date” | String

“time” | String

“utc-millisec” | long

“regex” | java.util.regex.Pattern

“color” | String

“style” | String

“phone” | String

“uri” | java.net.URI

“email” | String

“ip-address” | String

“ipv6” | String

“host-name” | String

“uuid” | java.util.UUID

extends

使用extends关键字可以实现 Java 中的继承。

比如,我们定义 flower.json

{
"type" : "object"
}

然后定义 rose.json,使其继承自 flower

{
"type" : "object",
"extends" : {
"$ref" : "flower.json"
}
}

最终我们生成的 Rose.java 为以下内容:

public class Rose extends Flower {
....
}

$ref

$ref关键字用于指定某一个属性的引用来源,在jsonschema2pojo中支持以下协议:

  • http://, https://
  • file://
  • classpath:, resource:, java: (all synonyms used to resolve schemas from the classpath).

我们定义 API 的时候一般是需要引用到其他我们定义的 Json Schema 文档。比如:

{
"type" : "object",
"properties" : {
"loggedInUser" : {
"$ref" : "user.json"
}
}
}

表明loggedInUser属性的类型是一个由user.json定义的类型。

{
"description" : "Tree node",
"type" : "object",
"properties" : {
"children" : {
"type" : "array",
"items" : {
"$ref" : "#"
}
}
}
}

这个表明 children 属性引用的是该 object 自身,所以这可以生成一个 Tree 类型的类。

public class TreeNode {
public List<TreeNode> getChildren() {...} public void setChildren(List<TreeNode> children) {...}
}

更多

  • javaEnumNames

    {
    "type" : "object",
    "properties" : {
    "foo" : {
    "type" : "string",
    "enum" : ["H","L"],
    "javaEnumNames" : ["HIGH","LOW"]
    }
    }
    }

    生成的类:

    public enum Foo {
    HIGH("H"),
    LOW("L")
    ...
    }
  • javaInterfaces

    {
    "javaInterfaces" : ["java.io.Serializable", "Cloneable"],
    "type" : "object"
    }

    生成的类:

    public class FooBar implements Serializable, Cloneable
    {
    ...
  • javaName

    {
    "type": "object",
    "properties": {
    "a": {
    "javaName": "b",
    "type": "string"
    }
    }
    }

    生成的类:

    public class MyClass {
    @JsonProperty("a")
    private String b; @JsonProperty("a")
    public String getB() {
    return b;
    } @JsonProperty("a")
    public void setB(String b) {
    this.b = b;
    }
    }

声明

本文绝大部分内容是引用的 jsonschame2pojo 的文档,更多内容请看官方文档 jsonschema2pojo.

使用 Json Schema 定义 API的更多相关文章

  1. Json Schema简介

    1. 引言 什么是Json Schema? 以一个例子来说明 假设有一个web api,接受一个json请求,返回某个用户在某个城市关系最近的若干个好友.一个请求的例子如下: { "city ...

  2. Json Schema 是什么?

    本文地址:Json Schema 是什么? 简单说,Json Schema 其实就是一个标准的 Json 串,它以一个 Json 串来描述我们需要的数据规范,并且支持注释以及验证 Json 文档,即我 ...

  3. 技术那么多,你想看看JSON Schema的测试吗?

    目录 1. 什么是JSON Schema? 2. 如何定义一个JSON Schema 3. 如何测试JSON Schema a) 使用JSON Schema validator GUI b) 在Jav ...

  4. JSON Schema 校验实例

    JSON Schema 简介 JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. ...

  5. Understanding JSON Schema

    json schema 在线校验器 译自:Understanding JSON Schema { "type": "object", "propert ...

  6. Map传参优雅检验,试试json schema validator

    背景 笔者目前所在团队的代码年代已久,早年规范缺失导致现在维护成本激增,举一个深恶痛疾的例子就是方法参数使用Map"一撸到底",说多了都是泪,我常常在团队内自嘲"咱硬是把 ...

  7. Schema、API Schema与MFn

    大部分知识都是相通的,Maya和USD在设计上有很多相似之处,USD的Schema粗看很难理解,但实际上与Maya的MFn有着异曲同工之处.这篇文章会简单介绍一下这两个知识点,做个对比,了解下它们在各 ...

  8. Json Schema的使用

    直接上案例: 在Web Api通讯中,客户端发送json数据,服务端反序列化json(json与某个类形成对应关系),在某些情况下,需要校验其上传的json是否合法. 服务端是使用Json.net(n ...

  9. json与api- 天气api 博客词频分析

    一.json基础 1.1 json的介绍 json现在成为各种程序与语言之间交互的一种数据格式,本质是文本,字符串. json有两种格式: 1.  类似字典  {k:v,k,v} 2.  类似列表 { ...

随机推荐

  1. 添加备注信息(Project)

    <Project2016 企业项目管理实践>张会斌 董方好 编著 就在任务信息的[高级]选项卡隔壁,还有一个[备注]选项卡,可别拿备注不当回事,因为任务名称的字数不能太多. 好吧,张同学也 ...

  2. nginx配置文件简析

    https://blog.csdn.net/wangbin_0729/article/details/82109693 #运行用户 user www-data; #启动进程,通常设置成和cpu的数量相 ...

  3. Spring核心原理之IoC容器初体验(2)

    本文节选自<Spring 5核心原理> 1 IoC与DI基本概念 IoC(Inversion of Control,控制反转)就是把原来代码里需要实现的对象创建.依赖,反转给容器来帮忙实现 ...

  4. AcWing3544. 寻找变化前的01序列

    题目描述 给你一个 01 序列,HDLC 协议处理的话,如果出现连续的 5 个 1 会补 1 个 0. 例如 1111110,会变成 11111010. 现在给你一个经过 HDLC 处理后的 01 序 ...

  5. JAVA获取六位随机数

    public static String getSixNum() { String str = "0123456789"; StringBuilder sb = new Strin ...

  6. Elasticsearch删除所有数据

    使用post请求 POST http://localhost:9200/索引/标签/_delete_by_query?pretty { "query": { "match ...

  7. 【LeetCode】519. Random Flip Matrix 解题报告(Python)

    作者: 负雪明烛 id: fuxuemingzhu 个人博客: http://fuxuemingzhu.cn/ 题目地址:https://leetcode.com/problems/random-fl ...

  8. C# 基础(更新中)

    Data Structure There're two types of variables in C#, reference type and value type. Enum: enum Colo ...

  9. The Longest Straight(FZUoj2216)

     Problem 2216 The Longest Straight Accept: 82    Submit: 203Time Limit: 1000 mSec    Memory Limit : ...

  10. 【机器学习】matplotlib库练习-函数绘图

    # 1创建2个图形区域,一个叫做green,大小是16,8,一个叫做red,大小是10,6 # 2绿色区域画一条绿色的正弦曲线,红色区域化两条线,一条是绿色的正弦曲线,一条是红色的余弦曲线 # 3在g ...