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
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:
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?
Comentários muito úteis
@robbinjanssen Se você quiser que eles fiquem no topo, faça algo assim: