Api-blueprint: Modularité

Pour les situations où il existe un grand nombre d'API, éventuellement sous le contrôle de différents groupes dans une entreprise, ce serait une aubaine absolue.

@rurounijones juste pour clarifier cette fonctionnalité signifie "Pour pouvoir diviser une description d'API en plusieurs fichiers".

Quelqu'un a-t-il une idée à ce sujet ? Selon mon commentaire précédent sur Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

Les options sont soit d'ajouter une fonction include/require en haut du blueprint, soit simplement de récupérer tous les blueprints à partir d'un répertoire et de les concaténer.

Les pensées?

La concaténation est plus simple mais je pense que l'exigence serait plus facile à utiliser car vous voudrez peut-être l'exiger, puis ajoutez quelque chose d'autre après.

S'agira-t-il simplement d'intégrer aveuglément le contenu du fichier comme s'il était défini dans le brevet, ou y aura-t-il une sorte de restriction sur le contenu du fichier (par exemple, peuvent-ils avoir leur propre en-tête yaml ? Conflits avec yaml parent ?) J'ai le sentiment qu'aucune restriction ne serait mieux, mais j'ai pensé que j'en parlerais.

@zdne

Tout d'abord, j'ai déjà un système rudimentaire pour gérer cela avec Grunt, en utilisant une simple concaténation de fichiers. Notre plan devenait ingérable, et c'était un moyen rapide et sale de le diviser en fichiers (à noter, un nombre arbitraire de fichiers, car ils sont concaténés par ordre du système de fichiers). J'ai posté mon Gruntfile avec une courte explication ici .

Étant donné que la concaténation est si simple à faire soi-même, il me semble logique qu'un outil "officiel" soit plus puissant. J'ai réfléchi davantage à cela, j'ai essayé de faire des recherches sur la façon dont cela est géré par d'autres systèmes.

1. Inclure/Exiger
   
   
   
   • Les inclusions seraient effectuées en haut d'un fichier et des parties du fichier seraient référencées à l'intérieur. Je pense que cela nécessite un système de référencement plus robuste que la syntaxe actuelle [Model Reference][] . Idéalement, n'importe quel nœud dans le fichier inclus serait adressable - donc on pourrait avoir quelque chose comme [github.Users.'Create A User'][] ou [github][POST /users] ou quelque chose comme ça. (Peut également avoir besoin d'un préfixe comme = ). Existe-t-il un meilleur moyen de référencer un nœud spécifique dans l'AST autre que le nom ou l'url + la méthode ?
   
   
   • Étant donné que vous disposez d'un bon moyen de déréférencer le contenu des nœuds, cela pourrait être fait avec le préprocesseur C qui viendrait avec de nombreuses fonctionnalités supplémentaires sans frais supplémentaires.
   
   
2. Système de template/Transclusion
   
   
   
   • Non-markdown - Le modèle serait écrit dans un langage de modèle distinct, de sorte qu'un fichier de modèle ne serait pas analysable par snowcrash. Un exemple de quelque chose comme ceci est grunt-readme , qui semble pouvoir fonctionner immédiatement pour modéliser un fichier de plan.
   
   
   • Markdown - Ce serait quelque chose comme la syntaxe =[]() ou :[]() dont nous avons discuté sur le problème du rédacteur. Ce serait toujours une démarque valide et analysable par snowcrash.
   
   
3. Tous les deux
   
   
   
   • Étant donné que vous définissez une syntaxe pour référencer les nœuds ( [github]['Create A User'] ) et la transclusion directe ( :[/github.md](/github.md) ), il semble que vous pourriez facilement avoir les deux. Peut-être qu'ils pourraient avoir la même syntaxe générale comme :[]() et l'analyseur détermine s'il s'agit d'un nœud ou d'une référence de fichier.
   
   

Des pensées à ce sujet? Me manque-t-il des options/outils ? Je penche en quelque sorte vers l'option "les deux" avec une syntaxe commune pour la transclusion et le déréférencement de nœud, mais c'est peut-être un peu trop.

Étant donné que la concaténation est si simple à faire soi-même, il me semble logique qu'un outil "officiel" soit plus puissant

Eh bien finalement peut-être oui, mais j'aimerais ne pas trop le concevoir et déployer quelque chose de léger et simple à la mendicité.

Au vu des problèmes actuels, des problèmes qu'il convient de résoudre, il s'agit principalement de :

1. Actifs (externes) référencés - # 20 et comme indiqué dans https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071
2. Diviser le plan en parties logiques plus gérables

Aux fins de la division, je considérerais uniquement un groupe de ressources ou une ressource (par exemple, pas une action, un exemple de transaction ou une demande). Du moins aux débuts.

Annonce 1 : Je pense que les _actifs référencés_ seraient élégamment traités par la proposition au n° 20 et discutés https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

Annonce 2 : Je ne compliquerais pas du tout. La seule chose que j'utiliserais pour la transclusion est la syntaxe de démarquage habituelle, par exemple [Some Text](path/to/blueprint/file.apib) ou [Some Text](path/to/blueprint/file.apib#resource-name) . Pour l'inclusion, je suivrais le même principe que pour les actifs dans le rédacteur, par exemple, utilisez : avant la référence. Quelque chose comme https://gist.github.com/zdne/8804418#aliens -question-aliens_question

Je pense que cela pourrait suffire pour le début ?

Je pense que cela pourrait suffire pour le début ?

D'accord. Je viens juste de réaliser que vous faites une distinction entre inclure les "actifs" et inclure les "ressources"/"groupes de ressources". J'avais pensé à chacun d'eux comme des "nœuds" à inclure à volonté.

Pour le deuxième point, j'ai pensé qu'il serait utile de référencer la syntaxe MultiMarkdown existante pour la transclusion :

This is some text.

{{some_other_file.txt}}

Another paragraph

Cela semble être un moyen simple d'inclure des ressources ? (ou bien, texte/nœuds arbitraires ?)

Alors pour préciser mon avis :

1. Je pense qu'une bonne syntaxe pour les actifs référencés serait :[]() ou =[]() comme discuté
2. Je pense qu'une bonne syntaxe pour la transclusion serait {{ }} telle qu'utilisée par multimarkdown.

Et aussi pour clarifier un peu de vocabulaire : je _pense_ que lorsque vous dites "inclusion", vous faites référence à ce que je veux dire lorsque je dis "transclusion", c'est-à-dire remplacer entièrement un espace réservé par du texte d'un autre fichier.

Si je comprends bien, la différence entre "référencer" et "inclusion"/"transclusion" est simplement pour le _rendu_, disons en html ou pdf. Pour l'analyseur, peu importe si un actif (par exemple) est référencé ou transclus, les mêmes résultats AST. Est-ce exact?

1. Je pense qu'une bonne syntaxe pour les actifs référencés serait : ou = comme discuté
2. Je pense qu'une bonne syntaxe pour la transclusion serait {{ }} telle qu'utilisée par le multi markdown.

Pourquoi avoir les deux au lieu d'une seule méthode ? Y a-t-il un avantage à faire une distinction syntaxique entre ces deux ? Personnellement, je préfère le numéro un car il s'affiche toujours comme un que vous pouvez suivre dans un simple Markdown ?

Je pense que lorsque vous dites "inclusion", vous faites référence à ce que je veux dire lorsque je dis "transclusion", c'est-à-dire remplacer entièrement un espace réservé par du texte d'un autre fichier.

D'accord, j'essaierai d'utiliser la transclusion à partir de maintenant. Merci!

Si je comprends bien, la différence entre "référencer" et "inclusion"/"transclusion" est simplement pour le rendu

Pas vraiment. À mon avis, la référence (création d'une référence) ne devrait vraiment ajouter qu'un lien vers la sortie (AST) et laisser le reste sur l'outillage (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

La translcusion devrait demander à l'analyseur (ou au préprocesseur) d'extraire le contenu...

Juste une mise à jour ici : c'est en effet prévu et très nécessaire. Nous travaillons sur l'outil qui rend cela possible. En attendant, si vous ne comptez pas sur l'éditeur en ligne Apiary, vous pouvez utiliser quelque chose comme https://gist.github.com/danvine/11087404 ou une autre approche similaire (je connais au moins quelques outils basés sur gulp pour cela).

Whisky prend désormais en charge l'extension .apib et facilite grandement l'édition de gros fichiers Markdown grâce à sa vue hiérarchique : http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ et http://25.io/mou/ prennent également en charge .apib si vous voulez une application de bureau (pour Mac)

Robert CrooksDirecteur des services d'apprentissage
Brightcove, Inc.

Le 29 décembre 2015, à 16h08, Kevin Ingersoll [email protected] a écrit :

Whisky prend désormais en charge le .apib
et rend l'édition de gros fichiers Markdown beaucoup plus facile avec sa vue de contour : http://vimeo.com/album/3108294/video/110486733

—
Répondez directement à cet e-mail ou consultez-le sur GitHub
.

Hey @bcls et @holic , merci d'avoir signalé ces éditeurs !

Connexe : https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

Une décision a-t-elle été prise par les principaux développeurs à ce sujet ? C'est en suspens depuis 2013 et aucune réponse claire n'a été donnée jusqu'à présent, pouvons-nous tirer une ligne à ce sujet s'il vous plaît ?

Hé @foxx , il n'y avait pas encore de décision claire sur celui-ci - je penche vers la syntaxe de transclusion introduite dans Hercule :

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

À l'exception de

`````` démarquage

• Modèle

+ Body

  ```
  :[](gist.json)
  ```

``````

Parce que les blocs de code doivent rester opaques pour l'analyseur/préprocesseur.

De plus, je ne pense pas que la transclusion devrait fonctionner à n'importe quel niveau - les fichiers transclus devraient être des plans valides eux-mêmes.

Quant à l'engagement à cet égard - il est assez élevé sur la feuille de route des fonctionnalités - mais pas encore d'ETA.

J'apprécierais tout commentaire ou réflexion à ce sujet, ainsi que sur la visibilité de la feuille de route des fonctionnalités.

Merci!

La syntaxe de transclusion semble être la meilleure proposition jusqu'à présent, c'est une approche élégante et propre, et meilleure que toutes les autres suggestions que j'ai vues jusqu'à présent. Fwiw, +1 de ma part.

des nouvelles à ce sujet?

L'approche avec transclusion me semble bonne, je n'y vois pas d'inconvénients.

Pour le moment, je suggère d'utiliser Hercule et la syntaxe :[Gist](blueprint/gist.md) . Travaillera à le rétroporter dans la spécification API Blueprint et la chaîne d'outils d'analyseur

Quelque chose a-t-il été fait pour ce problème ? J'aimerais également diviser un fichier apib plus volumineux en plusieurs.
Merci!

Hé @adams-sarah malheureusement pas de mon côté. J'approuve toujours l'utilisation d'Hercule (https://github.com/jamesramsay/hercule) car cela fonctionne plutôt bien - le seul inconvénient est que vous ne pourrez pas modifier les multiples fichiers sur Apiary.io. Faites-moi savoir si je peux aider d'une manière ou d'une autre !

+1 à l'utilisation d'hercule https://github.com/jamesramsay/hercule
nous l'utilisons depuis un moment maintenant et espérons qu'il trouvera toujours sa place dans les spécifications apib

:+1: pour l'ajout de cette fonctionnalité.

Je soutiens également une seule méthodologie TOC/index. La transclusion est un peu trop flexible et n'a pas été mise à l'échelle dans de grands documents basés sur wiki dans mon expérience passée.

Nous devrons certainement intégrer cela dans l'analyseur lui-même pour prendre en charge la carte source.

En attendant, nous avons préparé un exemple réel pour montrer comment utiliser Hercule - https://github.com/apiaryio/api.apiblueprint.org

@zdne dans notre utilisation de json-schema (via interagent/prmd), nous le divisons le long des lignes de ressources et appliquons essentiellement une structure de répertoire particulière pour impliquer des inclusions (plus ou moins, il construit un schéma de niveau supérieur qui contient tout le contenu du répertoire comme sous-schémas, donc ça change les niveaux des choses). Ceci est évidemment assez spécialisé dans ce que nous faisions et pas particulièrement approprié dans votre cas, mais je voulais partager notre expérience. Par rapport à cela, je pense que la transclusion semble beaucoup plus élégante/flexible, mais ce serait certainement bien d'avoir aussi des moyens simples d'avoir un TOC/index consolidé. Peut-être que c'est similaire à ce que nous avons fait, c'est-à-dire que vous créez un uber blueprint pour servir d'index, puis transclure/référencer les sous-blueprints qu'il contient. Je peux voir que cela se produit automatiquement comme étant agréable, mais aussi comme étant gênant si cela ne se produit pas pour faire exactement ce que vous voulez. Quoi qu'il en soit, c'est long de dire que je serais heureux de discuter/partager davantage mes expériences si cela pouvait être utile.

Quel est l'état de cette fonctionnalité ?
Nous utilisons le plan Pro dans Apiary.io et nous avons besoin de cette fonctionnalité

@DavidBM J'ai eu le même problème. comment j'ai contourné cela est d'avoir deux documents apiary.apib .

Non compilé

apiary-source.apib - une source non compilée qui utilise la fonctionnalité Inclure

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

Compiler

Vous pouvez simplement exécuter :

aglio --input apiary-source.apib --compile --output apiary.apib

Votre apiary.apib devrait maintenant inclure le contenu de blueprint/posts.apib à l'intérieur.

Salut merci! Oui, mais vous ne pouvez pas modifier les documents dans apiary.io

Nous avions déjà la solution sur mesure avec Hercule, mais l'intérêt de payer apiary pro pour nous est de laisser les chefs de produit mettre à jour la documentation sans entrer dans git. J'ai bien peur que ce soit un blocage complet pour nous et nous annulerons le contrat avec Apiary si cela n'est pas résolu.

Je ne m'attendrais pas à ce que ce soit dans cet état après avoir eu Hercule et d'autres outils pendant tant de temps disponibles.

C'est très très décevant :(

Bonjour à tous, je suis désolé d'être arrivé en retard et d'avoir rouvert et creusé de vieux trucs. Si ce n'est pas le bon endroit, veuillez m'en excuser. Mais, en faisant une recherche pour développer des maquettes de plans, j'ai trouvé cette discussion et c'est la plus proche que j'ai pu trouver jusqu'à présent.

J'ai du mal à diviser mes réponses par modèle :(. N'est-il pas possible de référencer un modèle dans un dossier différent ?
J'aimerais avoir dans mon dossier blueprints toutes mes requêtes, et, par exemple dans un dossier de modèles séparés tous mes modèles d'entités (fichiers MSON/MD/JSON/quel que soit, celui qui convient) pour les réutiliser facilement dans différentes réponses. Quelqu'un a-t-il réussi à faire cela?

Ce serait vraiment bien si ce problème attirait l'attention. Nous avons 26 000 lignes dans notre API Blueprint et cela le rend incroyablement difficile à gérer

Nous mettons en œuvre des tests de contrat à l'aide de Dredd et nous utilisons Aglio, mais ce serait formidable si cela était ajouté afin que nous n'ayons pas à le faire

L'une des raisons est que nous itérons beaucoup sur la conception :) Lorsque ce problème a été ouvert, il n'y avait pas de MSON et nous sommes toujours déchirés entre les transclusions et les références.

Mais pour info, quels sont vos besoins là-bas ? S'agit-il simplement d'une gestion multifichier et de la compilation d'un seul document en conséquence ou parlez-vous également de la réutilisation des modèles et du partage de fragments sur plusieurs documents de description d'API ?

L'une des raisons est que nous itérons beaucoup sur la conception :) Lorsque ce problème a été ouvert, il n'y avait pas de MSON et nous sommes toujours déchirés entre les transclusions et les références.

Mais pour info, quels sont vos besoins là-bas ? S'agit-il simplement d'une gestion multifichier et de la compilation d'un seul document en conséquence ou parlez-vous également de la réutilisation des modèles et du partage de fragments sur plusieurs documents de description d'API ?

Nous avons une réponse standard qui provient d'un groupe de nos terminaux. nous aimerions pouvoir définir cela à un seul endroit, près de la bibliothèque qui l'héberge, puis l'importer partout où nous en avons besoin pour y répondre.