Api-blueprint: Estendendo Estruturas de Dados

Criado em 12 nov. 2015  ·  6Comentários  ·  Fonte: apiaryio/api-blueprint

Olá, tenho uma pergunta / proposta sobre estruturas de dados. Talvez seja mais relacionado ao MSON, mas vou começar aqui. Para manter as estruturas de dados organizadas e organizadas, gostaria de ter o mínimo possível de dados duplicados, portanto, seria bom se as estruturas de dados pudessem se estender.

Suponha a seguinte estrutura de dados:

# 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)

No atributo links de Project1_Get eu reutilizo o objeto Project_Link que funciona muito bem. Mas suponha que eu precise da seguinte DataStructure também:

## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)

Agora há dados duplicados em minhas estruturas de dados porque Project1_Identifier contém o atributo type e id , mas também Project1_Get contém. Seria ótimo se eu pudesse fazer o seguinte:

# 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)

No exemplo a seguir, o redator retorna erros:

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

Comentários muito úteis

@robbinjanssen Se você quiser que eles fiquem no topo, faça algo assim:

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

Todos 6 comentários

Isso deveria ser possível. Parece que o problema está com _ no nome do tipo. Renomear Project1_Get para X pareceu funcionar.

Observação _ é um caractere reservado de acordo com a especificação MSON - consulte https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#6 -reserved-characters - keywords

No entanto, acredito que estamos tendo um bug aqui em nossa implementação cc @pksunkara

Você está correto, o redator agora aprova a redução usando o seguinte exemplo:

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)

Mas na verdade eu acho que é um bug, tanto aglio quanto a interface apiaryio estão interpretando errado:

screen shot 2015-11-12 at 11 14 41

Edit: ops, vejo que o apiário está corrigindo! Mas ele coloca o tipo / id na parte inferior neste caso. Minha preferência seria colocá-lo no topo.

Vou esperar antes de refatorar meus documentos novamente ;-)

@robbinjanssen Se você quiser que eles fiquem no topo, faça algo assim:

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

@pksunkara legal, obrigado!

Um exemplo simples do bug é o seguinte:

# 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 Acho que isso está relacionado a https://github.com/apiaryio/snowcrash/issues/335. O que você disse?

Esta página foi útil?
0 / 5 - 0 avaliações

Questões relacionadas

annappropriate picture annappropriate  ·  5Comentários

pete001 picture pete001  ·  6Comentários

agougousis picture agougousis  ·  8Comentários

bazo picture bazo  ·  8Comentários

AlexKorovyansky picture AlexKorovyansky  ·  4Comentários