Api-blueprint: 扩展数据结构

创建于 2015-11-12  ·  6评论  ·  资料来源: apiaryio/api-blueprint

嗨,我有一个关于数据结构的问题/建议。 也许这与 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包含typeid属性,但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
Language Parser Implementation Bug

最有用的评论

@robbinjanssen如果您希望他们处于领先

## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
    + number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)

所有6条评论

这应该是可能的。 似乎问题出在类型名称中的_上。 将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 接口都呈现错误:

screen shot 2015-11-12 at 11 14 41

编辑:哎呀,我看到 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
此页面是否有帮助?
0 / 5 - 0 等级