RAML 1.0 - 单个响应的多个示例
Posted
技术标签:
【中文标题】RAML 1.0 - 单个响应的多个示例【英文标题】:RAML 1.0 - Multiple Examples for a Single Response 【发布时间】:2016-12-22 03:01:07 【问题描述】:我无法在任何地方找到使用!include
演示多个示例的任何代码。我正在尝试以下操作:
200:
description: Successful project creation
body:
application/json:
type: JiraResponseSuccess
example: !include examples/jira/projects/success/CreateSuccess.json
400:
description: User error
body:
application/json:
type: JiraResponseError
examples:
username:
!include examples/jira/projects/fail/user/UsernameFail.json
projectKey:
!include examples/jira/projects/fail/user/ProjectKeyFail.json
第一个示例呈现良好(只有一个响应),而第二个则没有。 syntax 是正确的,但我不明白为什么它会在 !include
语句中窒息。我有错误还是只需要等待工具赶上?
【问题讨论】:
看起来多重响应还没有实现:github.com/raml-org/raml-spec/issues/24 【参考方案1】:我们一直在为我们的 RAML 文档做同样的事情,而且这个解决方案也适用于 RAML 版本 0.8。您可以灵活地更改内容类型,甚至可以包含空格和其他基本符号以提高可读性。
正如@manatico 所说,内容类型不必必须是有效类型,因为 RAML 不会对其进行验证。它只是认识到存在差异,允许列出多个示例。为了使客户更清楚,我建议在实际内容类型前面加上任何适合您需要的内容,以提供更多示例。
get:
responses:
200:
body:
application/json - Example - Filtering by AppId:
example: |
"tagId": "475889c9-773d-462a-a4ec-099242308170"
"appId": "12"
"tagName": "school",
"status": "ACTIVE"
application/json - Example - No Filtering:
example: |
"tagId": "58237aa0-3fa6-11e6-a16b-6d3f576c1098",
"tagName": "exercise",
"status": "ACTIVE"
,
"tagId": "06b8b7b5-8e6b-40e9-9e48-f87dec0665e4",
"tagName": "camping",
"status": "INACTIVE"
【讨论】:
【参考方案2】:您可以为正文响应示例指定不同的内容类型,即使它们实际上不是真正的内容类型:
200:
body:
role/admin:
example: !include http/list-res-200.json
role/admin-Search-for-User:
example: !include http/search-as-admin-res-200.json
role/member-Search-for-User:
example: !include http/search-as-member-res-200.json
只是为了文档工作正常,我用RAML2html 解析为 HTML,一切都没有问题。
【讨论】:
以上是关于RAML 1.0 - 单个响应的多个示例的主要内容,如果未能解决你的问题,请参考以下文章