RAML 0.8中引用JSON Schema的方法詳解
阿新 • • 發佈:2019-02-02
在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 ...
或
2.使用schema引用資源... 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 ...
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