Salut, j'ai une question/proposition sur les structures de données. C'est peut-être plus lié à MSON, mais je vais commencer ici. Pour garder les structures de données bien rangées, j'aimerais le moins de données en double possible, c'est pourquoi ce serait bien si les structures de données pouvaient s'étendre les unes les autres.
Supposons la structure de données suivante :
# 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)
Dans l'attribut links
de Project1_Get
je réutilise l'objet Project_Link
qui fonctionne très bien. Mais supposons que j'ai également besoin de la DataStructure suivante :
## Project1_Identifier (object)
+ type: `projects` (string, required)
+ id: `5` (string, required)
Maintenant, il y a des données en double dans mes structures de données car le Project1_Identifier
contient les attributs type
et id
, mais aussi le Project1_Get
contient. Ce serait super si je pouvais faire les choses suivantes :
# 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)
Dans l'exemple suivant, le rédacteur renvoie des erreurs :
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
Cela devrait être possible. On dirait que le problème vient du _
dans le nom du type. Renommer Project1_Get
en X
semblait fonctionner.
Remarque _
est un caractère réservé par spécification MSON - voir https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#6 -reserved-characters--keywords
Cependant, je pense que nous avons un bug ici dans notre implémentation cc @pksunkara
Vous avez raison, le rédacteur approuve maintenant la démarque en utilisant l'exemple suivant :
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)
Mais en effet, je pense que c'est un bug, à la fois aglio et l'interface apiaryio le rendent mal :
Edit : oups, je vois qu'apiaryio le rend correct ! Mais il place le type/id en bas dans ce cas. Ma préférence serait de le placer en haut.
J'attendrai avant de refactoriser à nouveau mes docs ;-)
@robbinjanssen Si vous voulez qu'ils soient au sommet, veuillez faire quelque chose comme ceci :
## Project1Get
+ Include ProjectIdentifier
+ attributes (object, required)
+ number: `PRO-5` (string) - A readable identifier for employees to refer to projects.
+ links (ProjectLink, required)
@pksunkara cool merci !
Un exemple simple du bogue est le suivant :
# 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 Je pense que cela est lié à https://github.com/apiaryio/snowcrash/issues/335. Que dites-vous?
Commentaire le plus utile
@robbinjanssen Si vous voulez qu'ils soient au sommet, veuillez faire quelque chose comme ceci :