RAML 0.8中引用JSON Schema的方法详解

在RAML 0.8的规范中，以Schema的方式定义资源Resources。

为了能够引用JSON Schema，提供了两个关键字schemas和schema。schemas用以声明资源，而schema用以引用资源。

根据是否在raml文件中定义JSON Schema，引用JSON Schema有两种方式，一种是在raml文件中引用独立的JSON Schema文件，另一种是在raml文件中直接使用JSON Schema片段。

1.使用schemas声明资源

...
schemas:
  - User:  schema/user.json
    Users: schema/users.json
    Org:   schema/org.json
    Orgs:  schema/orgs.json
...
           

或

...
schemas:
  - !include path-to-canonical-schemas/canonicalSchemas.raml
  - File:       !include path-to-schemas/filesystem/file.xsd
    FileUpdate: !include path-to-schemas/filesystem/fileupdate.xsd
    Files:      !include path-to-schemas/filesystem/files.xsd
    Dir:        !include path-to-schemas/filesystem/dir.xsd
    Dirs:       !include path-to-schemas/filesystem/dirs.xsd
...
           

2.使用schema引用资源

1) 对于已经声明过的资源，可以在后续raml文件中直接引用

/files:
  get:
    responses:
      200:
        body:
          application/xml:
            schema: Files
           

2) 也可以引用从未声明过的资源

/jobs:
  displayName: Jobs
  post:
    description: Create a Job
    body:
      text/xml:
        schema: !include job.xsd
      application/json:
        schema: !include job.schema.json
           

或

/jobs:
  displayName: Jobs
  post:
    description: Create a Job
    body:
      text/xml:
        schema: |
          <xs:schema attributeFormDefault="unqualified"
                     elementFormDefault="qualified"
                     xmlns:xs="http://www.w3.org/2001/XMLSchema">
            <xs:element name="api-request">
              <xs:complexType>
                <xs:sequence>
                  <xs:element type="xs:string" name="input"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:schema>
      application/json:
        schema: |
          {
            "$schema": "http://json-schema.org/draft-03/schema",
            "properties": {
                "input": {
                    "required": false,
                    "type": "string"
                }
            },
            "required": false,
            "type": "object"
          }
           

注意，对于application/x-www-form-urlencoded或multipart/form-data时，不能使用schema。

3. 补充：与schema类似，RAML 0.8中还提供了example，可以引用JSON Schema。

application/json:
        schema: !include job.schema.json
        example: |
          {
            "input": "s3://zencodertesting/test.mov"
          }
           

或

application/json:
        example: !include examples/instagram-v1-media-popular-example.json
           

参考链接：

https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md