如何将JSON转换为RAML（附教程）

方石剑
340 阅读3分钟

如何将JSON转换为RAML

在使用RAML创建API规范时，很多时候，我们需要从JSON有效载荷中创建一个RAML库或DataType。我们可以通过使用MuleSoft Anypoint Design Center这样的API建模工具来手动完成。然而，如果JSON的有效载荷非常大，有多个属性，转换任务就会变得费时且容易出错。最好是使用有助于自动转换的工具。ramldt2jsonschema就是这样一个工具。它是一个CLI和库，用于将RAML 1.0数据类型转换为JSON模式，然后再转换。它在引擎盖下使用webapi-parser。

转换过程可分为三个步骤。

  1. 将JSON文件转换为JSON模式- 我们可以使用任何免费的在线JSON到JSON模式转换器来实现这一目的。其中一些，如JSON-Formatter和Code-Beautify，将JSON转换为JSON模式的06草案版本，而另一些，如JSON-to-Schema-Converter，将JSON转换为JSON模式的04草案版本（07版本是最新版本）。
  2. 根据需要修改JSON模式的字段 - 如果一些字段需要变成可选，或者需要应用带有最大/最小值的特定字段范围，这可以在转换后的JSON模式中完成。
  3. 将JSON模式转换为RAML库 - 在这一步，使用ramldt2jsonschemaCLI将JSON模式转换为RAML库，如下面的例子所示。

ramldt2jsonschema的用法

安装

壳体

npm install -g ramldt2jsonschema

这将安装两个命令行工具。

  • dt2js:RAML数据类型<>JSON模式
  • js2dt:JSON模式<>RAML数据类型

dt2js:

壳体

dt2js <ramlFile> <ramlTypeName> --draft=[version] [--validate]

选择

  • <ramlFile>:包含至少一个RAML数据类型的文件的路径（例如path/to/api.raml）。
  • <ramlTypeName>:转换为JSON模式的RAML类型名称
  • --draft:可选的转换为JSON模式草案的版本。支持的值是。04、06和07年
  • --validate:用Ajv验证输出的JSON模式。如果模式无效，则抛出一个错误。需要安装 "ajv"。(默认：false)

js2dt:

壳体

js2dt <jsonFile> <ramlTypeName> [--validate]

选项。

  • <jsonFile>:JSON模式文件的路径（例如：path/to/schema.json）。
  • <ramlTypeName>:赋予导出的RAML数据类型的RAML类型名称
  • --validate:用webapi-parser验证输出的RAML。如果无效，则抛出一个错误。(默认：false)

例子1

JSON输入样本。

JSON

{
	"status": "OK",
    "apiName": "salesforce-sys-api",
    "apiVersion": "1.3.0",
    "timestamp": "2020-08-01T13:15:25.000Z",
    "dependencies": [
        {
            "name": "Salesforce",
            "status": "UP"
        }
    ]
}

转换后的JSON模式。

JSON

{
  "$schema": "http://json-schema.org/draft-04/schema#",  
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "apiName": {
      "type": "string",
      "required": false //modified
    },
    "apiVersion": {
      "type": "string",
      "enum": ["v1","v2"]  //modified
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"  //modified              
    },
    "dependencies": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "status": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "status"
          ]
        }
      ]
    }
  },
  "required": [
    "status",
    "apiName",
    "apiVersion",
    "timestamp",
    "dependencies"
  ]
}

JSON模式到RAML库的转换。

YAML

#%RAML 1.0 Library
types:
  PingResponse:
    type: object
    additionalProperties: true
    properties:
      status:
        type: string
        required: true
      apiName:
        type: string
        required: false
      apiVersion:
        enum:
          - v1
          - v2
        type: string
        required: true
      timestamp:
        type: datetime
        required: true
      dependencies:
        (amf-tuple): true
        required: true

例2

JSON输入样本。

JSON

{
      "id": 157538,
      "date": "2017-07-21T10:30:34",
      "date_gmt": "2017-07-21T17:30:34",
      "guid": {
          "rendered": "https://www.sitepoint.com/?p=157538"
      },
      "modified": "2017-07-23T21:56:35",
      "modified_gmt": "2017-07-24T04:56:35",
      "slug": "why-the-iot-threatens-your-wordpress-site-and-how-to-fix-it",
      "status": "publish",
      "type": "post",
      "link": "https://www.sitepoint.com/why-the-iot-threatens-your-wordpress-site-and-how-to-fix-it/",
      "title": {
          "rendered": "Why the IoT Threatens Your WordPress Site (and How to Fix It)"
      },
      "content": {
          "rendered": "XYZ"
      },
      "excerpt": {
          "rendered": "ABC"
      },
      "author": 72546,
      "featured_media": 157542,
      "comment_status": "open",
      "ping_status": "closed",
      "sticky": false,
      "template": "",
      "format": "standard",
      "meta": [],
      "categories": [
          6132
      ],
      "tags": [
          1798,
          6298
      ],
}

转换后的JSON模式。

JSON

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "date": {
      "type": "string"
    },
    "date_gmt": {
      "type": "string"
    },
    "guid": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "modified": {
      "type": "string"
    },
    "modified_gmt": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "link": {
      "type": "string"
    },
     "title": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "content": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "excerpt": {
      "type": "object",
      "properties": {
        "rendered": {
          "type": "string"
        }
      },
      "required": [
        "rendered"
      ]
    },
    "author": {
      "type": "integer"
    },
    "featured_media": {
      "type": "integer"
    },
    "comment_status": {
      "type": "string"
    },
    "ping_status": {
      "type": "string"
    },
    "sticky": {
      "type": "boolean"
    },
    "template": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "meta": {
      "type": "array",
      "items": {}
    },
    "categories": {
      "type": "array",
      "items": [
        {
          "type": "integer"
        }
      ]
    },
    "tags": {
      "type": "array",
      "items": [
        {
          "type": "integer"
        },
        {
          "type": "integer"
        }
      ]
    }
  },
  "required": [
    "id",
    "date",
    "date_gmt",
    "guid",
    "modified",
    "modified_gmt",
    "slug",
    "status",
    "type",
    "link",
    "title",
    "content",
    "excerpt",
    "author",
    "featured_media",
    "comment_status",
    "ping_status",
    "sticky",
    "template",
    "format",
    "meta",
    "categories",
    "tags"
  ]
}

JSON模式到RAML库的转换。

YAML

#%RAML 1.0 Library
types:
  WordPress:
    type: object
    additionalProperties: true
    properties:
      id:
        type: integer
        required: true
      date:
        type: string
        required: true
      date_gmt:
        type: string
        required: true
      guid:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      modified:
        type: string
        required: true
      modified_gmt:
        type: string
        required: true
      slug:
        type: string
        required: true
      status:
        type: string
        required: true
      type:
        type: string
        required: true
      link:
        type: string
        required: true
      title:
        type: object
        additionalProperties: true
        properties:
           rendered:
            type: string
            required: true
        required: true
      content:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      excerpt:
        type: object
        additionalProperties: true
        properties:
          rendered:
            type: string
            required: true
        required: true
      author:
        type: integer
        required: true
      featured_media:
        type: integer
        required: true
      comment_status:
        type: string
        required: true
      ping_status:
        type: string
        required: true
      sticky:
        type: boolean
        required: true
      template:
        type: string
        required: true
      format:
        type: string
        required: true
      meta:
        type: array
        items:
          type: any
        required: true
      categories:
        (amf-tuple): true
        required: true
      tags:
        (amf-tuple): true
        required: true

局限性。

  1. 数组不会被转换为单个记录/项目，它们被显示为amf-tuple

JSON 转换（命令） 模式

DZone贡献者所表达的观点是他们自己的。

avatar
文章
阅读
粉丝