1. 程式人生 > >RAML 0.8中引用JSON Schema的方法詳解

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