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

迈不过友情╰ 2022-06-09 14:16 195阅读 0赞

在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