嗨,我有一个关于数据结构的问题/建议。 也许这与 MSON 相关,但我将从这里开始。 为了保持数据结构的整洁,我希望尽可能少的重复数据,因此如果数据结构可以相互扩展就好了。
假设以下数据结构:
# Data Structures
## Project_Link (object)
+ self: `https://test.api.com/projects/5` (string, required)
## Project1_Get (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)
在links
属性Project1_Get
我重复使用Project_Link
对象,它的伟大工程。 但假设我还需要以下 DataStructure:
## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
现在我的数据结构中有重复数据,因为Project1_Identifier
包含type
和id
属性,但Project1_Get
包含它。 如果我能做到以下几点就好了:
# Data Structures
## Project1_Link (object)
+ self: `https://test.api.com/projects/5` (string, required)
## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
## Project1_Get (Project_Identifier) <--- Extend!
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project1_Link, required)
在以下示例中,起草者返回错误:
FORMAT: 1A
HOST: https://test.api.com/
# Test API
Hi, welcome to the API!
# Group Projects
Wow, we are using projects!
### Retrieve single project [GET /projects/{id}]
+ Parameters
+ id: `5` (string, required)
+ Response 200 (application/json)
+ Attributes (object)
+ data (Project1_Get, required)
# Data Structures
## Project_Link (object)
+ self: `https://test.api.com/projects/5` (string, required)
## Project_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
## Project1_Get (Project_Identifier)
+ type: `projects` (string, required)
+ id: `5` (string, required)
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (Project_Link, required)
user<strong i="25">@development</strong>:/srv/www/docs$ drafter -v
v2.0.0-pre.1
user<strong i="26">@development</strong>:/srv/www/docs$ drafter --validate docs.md --use-line-num
error: (4) base type 'Project1_Get' is not defined in the document; line 16, column 11 - line 16, column 40
warning: (8) unable to find the symbol `Project1_Get` in the list of named types; line 16, column 11 - line 16, column 40
这应该是可能的。 似乎问题出在类型名称中的_
上。 将Project1_Get
重命名X
似乎有效。
注意_
是每个 MSON 规范的保留字符 - 请参阅https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#6 -reserved-characters--keywords
但是我相信我们的实现中存在一个错误 cc @pksunkara
您是对的,起草者现在使用以下示例批准降价:
FORMAT: 1A
HOST: https://test.api.com/
# Test API
Hi, welcome to the API!
# Group Projects
Wow, we are using projects!
### Retrieve single project [GET /projects/{id}]
+ Parameters
+ id: `5` (string, required)
+ Response 200 (application/json)
+ Attributes (object)
+ data (Project1Get, required)
# Data Structures
## ProjectLink (object)
+ self: `https://test.api.com/projects/5` (string, required)
## ProjectIdentifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
## Project1Get (ProjectIdentifier)
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)
但确实我认为这是一个错误, aglio和 apiaryio 接口都呈现错误:
编辑:哎呀,我看到 apiaryio 是正确的! 但在这种情况下,它会将类型/ID 放在底部。 我的偏好是将它放在顶部。
我会在再次重构我的文档之前等待;-)
@robbinjanssen如果您希望他们处于领先
## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)
@pksunkara很酷,谢谢!
该错误的一个简单示例如下:
# GET /projects
+ Response 200 (application/json)
+ Attributes (object)
+ data (B_B, required)
# Data Structures
## A_A
+ a: a
## B_B (A_A)
+ b: b
@zdne我认为这与https://github.com/apiaryio/snowcrash/issues/335有关
最有用的评论
@robbinjanssen如果您希望他们处于领先