Api-blueprint: Modularität

Für Situationen, in denen es eine große Anzahl von APIs gibt, die möglicherweise von verschiedenen Gruppen in einem Unternehmen kontrolliert werden, wäre dies ein absoluter Glücksfall.

@rurounijones Nur zur Verdeutlichung, diese Funktion soll "eine API-Beschreibung in mehrere Dateien aufteilen können".

Hat jemand irgendwelche Gedanken dazu? Gemäß meinem vorherigen Kommentar zu Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

Die Optionen sind entweder eine Include/Require-Funktion oben auf dem Blueprint hinzuzufügen oder einfach alle Blueprints aus einem Verzeichnis zu holen und sie miteinander zu verketten.

Gedanken?

Die Verkettung ist einfacher, aber ich denke, dass require einfacher zu verwenden wäre, da Sie es vielleicht möchten, und fügen Sie danach etwas anderes hinzu.

Wird der Inhalt der Datei einfach blind eingefügt, als wäre er im Patent definiert, oder wird der Inhalt der Datei irgendwie eingeschränkt (z. B. können sie ihren eigenen YAML-Header haben? Konflikte mit übergeordnetem YAML?) Ich habe das Gefühl, dass keine Einschränkung besser wäre, aber ich dachte, ich würde es ansprechen.

@zdne

Zunächst einmal habe ich ein rudimentäres System, um dies bereits mit Grunt zu verwalten, indem ich eine einfache Dateiverkettung verwende. Unsere Blaupause wurde unüberschaubar, und dies war eine schnelle und schmutzige Methode, sie in Dateien aufzuteilen (beachten Sie, dass beliebig viele Dateien, weil sie durch die Dateisystemreihenfolge verkettet sind). Ich habe mein Gruntfile mit einer kurzen Erklärung hier gepostet.

Angesichts der Tatsache, dass die Verkettung so einfach selbst zu rollen ist, macht es für mich Sinn, dass ein "offizielles" Tool leistungsfähiger sein sollte. Ich habe mehr darüber nachgedacht und versucht zu recherchieren, wie dies von anderen Systemen gehandhabt wird.

1. Einschließen/Anfordern
   
   
   
   • Einschlüsse würden am Anfang einer Datei erfolgen, und Teile der Datei würden darin referenziert. Ich denke, dies erfordert ein robusteres Referenzierungssystem als die aktuelle [Model Reference][] -Syntax. Idealerweise wäre jeder Knoten in der enthaltenen Datei adressierbar - also könnte man so etwas wie [github.Users.'Create A User'][] oder [github][POST /users] oder so etwas haben. (Möglicherweise ist auch ein Präfix wie = erforderlich). Gibt es eine bessere Möglichkeit, auf einen bestimmten Knoten im AST zu verweisen, als Name oder URL+Methode?
   
   
   • Da Sie Knoteninhalte gut dereferenzieren können, könnte dies mit dem C-Präprozessor erfolgen, der ohne zusätzliche Kosten viele zusätzliche Funktionen bietet.
   
   
2. Templating-System/Transklusion
   
   
   
   • Nicht-Markdown – Die Vorlage würde in einer separaten Vorlagensprache geschrieben, sodass eine Vorlagendatei nicht von Snowcrash analysiert werden könnte. Ein Beispiel für so etwas ist grunt-readme , das so aussieht, als könnte es sofort einsatzbereit sein, um eine Blaupausendatei zu erstellen.
   
   
   • Markdown – Das wäre so etwas wie die =[]() oder :[]() Syntax, die wir im Drafter-Problem besprochen haben. Es wäre immer noch ein gültiger Markdown und durch Snowcrash parsbar.
   
   
3. Beide
   
   
   
   • Da Sie eine Syntax für die Referenzierung von Knoten ( [github]['Create A User'] ) und die direkte Transklusion ( :[/github.md](/github.md) ) definieren, scheint es, als könnten Sie beides problemlos haben. Vielleicht könnten sie dieselbe allgemeine Syntax wie :[]() haben und der Parser bestimmt, ob es sich um einen Knoten oder eine Dateireferenz handelt.
   
   

Irgendwelche Gedanken dazu? Fehlen mir einige Optionen/Tools? Ich tendiere eher zur Option "beide" mit einer gemeinsamen Syntax für die Transklusion und die Dereferenzierung von Knoten, aber das ist vielleicht ein bisschen viel.

Angesichts der Tatsache, dass die Verkettung so einfach selbst zu rollen ist, macht es für mich Sinn, dass ein "offizielles" Tool leistungsfähiger sein sollte

Nun, irgendwann vielleicht ja, aber ich möchte es nicht überdesignen und etwas Schlankes und Einfaches auf den Markt bringen.

Betrachtet man die aktuellen Probleme, die angegangen werden müssen, sind es vor allem:

1. Referenzierte (externe) Assets – #20 und wie in https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 besprochen
2. Blaupause in überschaubarere logische Teile aufteilen

Zum Zweck der Aufteilung würde ich nur entweder eine Ressourcengruppe oder eine Ressource betrachten (z. B. keine Aktion, kein Transaktionsbeispiel oder eine Anfrage). Zumindest in den Anfängen.

Anzeige 1: Ich denke, _referenzierte Assets_ würden durch den Vorschlag in Nr. 20 elegant angesprochen und unter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 diskutiert

Ad 2: Ich würde es überhaupt nicht verkomplizieren. Das einzige, was ich für die Transklusion verwenden würde, ist die reguläre Markdown-Syntax, z. B. [Some Text](path/to/blueprint/file.apib) oder [Some Text](path/to/blueprint/file.apib#resource-name) . Für die Aufnahme würde ich dem gleichen Prinzip folgen wie für Assets im Verfasser, z. B. : vor der Referenz verwenden. Etwas wie https://gist.github.com/zdne/8804418#aliens -question-aliens_question

Ich denke das könnte für den Anfang reichen?

Ich denke das könnte für den Anfang reichen?

Einverstanden. Ich stelle gerade fest, dass Sie zwischen dem Einschließen von "Assets" und dem Einschließen von "Ressourcen" / "Ressourcengruppen" unterscheiden. Ich hatte an sie alle als "Knoten" gedacht, die nach Belieben eingeschlossen werden konnten.

Für den zweiten Punkt hielt ich es für nützlich, auf die vorhandene MultiMarkdown-Syntax für die Transklusion zu verweisen:

This is some text.

{{some_other_file.txt}}

Another paragraph

Dies scheint eine einfache Möglichkeit zu sein, Ressourcen einzubeziehen? (oder tatsächlich willkürlicher Text/Knoten?)

Also um meine Meinung zu verdeutlichen:

1. Ich denke, eine gute Syntax für referenzierte Assets wäre wie besprochen :[]() oder =[]()
2. Ich denke, eine gute Syntax für die Transklusion wäre {{ }} , wie sie von Multimarkdown verwendet wird.

Und auch um einige Vokabeln zu klären: Ich _denke_, wenn Sie "Einschluss" sagen, beziehen Sie sich auf das, was ich meine, wenn ich "Transklusion" sage, nämlich einen Platzhalter vollständig durch Text aus einer anderen Datei zu ersetzen.

Wenn ich das richtig verstehe, dient der Unterschied zwischen "Referenzierung" und "Einschluss"/"Einschluss" einfach dem _Rendering_, sagen wir in HTML oder PDF. Für den Parser spielt es keine Rolle, ob ein Asset (zum Beispiel) referenziert oder transkludiert wird, die gleichen AST-Ergebnisse. Ist das korrekt?

1. Ich denke, eine gute Syntax für referenzierte Assets wäre : or = wie besprochen
2. Ich denke, eine gute Syntax für die Transklusion wäre {{ }}, wie sie von Multi-Markdown verwendet wird.

Warum beides statt nur eine Methode? Gibt es einen Vorteil für die syntaktische Unterscheidung zwischen diesen beiden? Persönlich bevorzuge ich Nummer eins, da es immer noch so gerendert wird, wie Sie in einem einfachen Markdown folgen können?

Ich denke, wenn Sie "Einschluss" sagen, beziehen Sie sich auf das, was ich meine, wenn ich "Transklusion" sage, dh einen Platzhalter vollständig durch Text aus einer anderen Datei zu ersetzen.

Stimme zu, werde von nun an versuchen, Transklusion zu verwenden. Danke!

Wenn ich das richtig verstehe, dient der Unterschied zwischen "Referenzieren" und "Einschließen" / "Einschließen" lediglich dem Rendern

Nicht wirklich. Meiner Meinung nach sollte das Verweisen (Erstellen einer Referenz) wirklich nur einen Link zur Ausgabe (AST) hinzufügen und den Rest den Tools überlassen (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

Translcusion sollte den Parser (oder Präprozessor) anweisen, den Inhalt hineinzuziehen ...

Nur ein Update hier: Dies ist in der Tat geplant und dringend erforderlich. Wir arbeiten an dem Tool, das dies ermöglicht. In der Zwischenzeit, wenn Sie sich nicht auf den Online-Editor von Apiary verlassen, können Sie so etwas wie https://gist.github.com/danvine/11087404 oder einen anderen, ähnlichen Ansatz verwenden (ich kenne zumindest einige Gulp-basierte Tools dafür).

Whiskey unterstützt jetzt die Erweiterung .apib und erleichtert mit seiner Gliederungsansicht das Bearbeiten großer Markdown-Dateien erheblich: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ und http://25.io/mou/ unterstützen auch .apib, wenn Sie eine Desktop-App (für Mac) wünschen.

Robert CrooksLeiter der Lerndienste
Brightcove, Inc

Am 29. Dezember 2015 um 16:08 Uhr schrieb Kevin Ingersoll [email protected] :

Whiskey unterstützt jetzt die .apib
-Erweiterung und erleichtert mit der Gliederungsansicht das Bearbeiten großer Markdown-Dateien erheblich: http://vimeo.com/album/3108294/video/110486733

—
Antworten Sie direkt auf diese E-Mail oder zeigen Sie sie auf GitHub an
.

Hey @bcls und @holic , vielen Dank für den Hinweis auf diese Editoren!

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

Wurde diesbezüglich von den Core-Entwicklern eine Entscheidung getroffen? Es ist seit 2013 ausstehend und es wurde bisher keine eindeutige Antwort gegeben, können wir bitte einen Schlussstrich ziehen?

Hey @foxx , hier gab es noch keine klare Entscheidung – ich tendiere zu der in Hercule eingeführten Transklusionssyntax:

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)

Mit Ausnahme von

`````` Abschlag

• Modell

+ Body

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

``````

Denn die Codeblöcke sollen für den Parser/Präprozessor undurchsichtig bleiben.

Ich denke auch nicht, dass die Transklusion auf irgendeiner Ebene funktionieren sollte – die Dateien, die transkludiert werden, sollten selbst gültige Blaupausen sein.

Was das Engagement betrifft – es steht ziemlich weit oben auf der Feature-Roadmap – aber noch keine ETA.

Ich würde mich über Kommentare oder Gedanken dazu und auch zur Sichtbarkeit der Feature-Roadmap freuen.

Danke!

Die Transklusionssyntax scheint bisher der beste Vorschlag zu sein, es ist ein eleganter und sauberer Ansatz und besser als alle anderen Vorschläge, die ich bisher gesehen habe. Fwiw, +1 von mir.

Gibt es Neuigkeiten zu diesem Thema?

ansatz mit transklusion erscheint mir gut, ich sehe darin keine nachteile.

Ich schlage vorerst vor, Hercule und die :[Gist](blueprint/gist.md) -Syntax zu verwenden. Wird darauf hinarbeiten, es zurück in die API-Blueprint-Spezifikation und die Parser-Toolchain zu portieren

Wurde für dieses Problem etwas unternommen? Ich möchte auch eine größere Apib-Datei in mehrere aufteilen.
Danke!

Hey @adams-sarah leider nicht von meiner Seite. Ich befürworte immer noch die Verwendung von Hercule (https://github.com/jamesramsay/hercule), da es ziemlich gut funktioniert – der einzige Nachteil ist, dass Sie die mehreren Dateien bei Apiary.io nicht bearbeiten können. Sag Bescheid, wenn ich irgendwie helfen kann!

+1 zur Verwendung von Hercule https://github.com/jamesramsay/hercule
Wir verwenden es jetzt schon seit einiger Zeit und hoffen, dass es immer noch seinen Weg in die Apib-Spezifikationen findet

:+1: für das Hinzufügen dieser Funktion.

Ich unterstütze auch eine Single-TOC/Index-Methodik. Transklusion ist ein bisschen zu flexibel und hat sich in meinen bisherigen Erfahrungen nicht in großen Wiki-basierten Dokumenten skaliert.

Wir müssen dies definitiv in den Parser selbst backen, um die Quellkarte zu unterstützen.

In der Zwischenzeit haben wir ein reales Beispiel vorbereitet, um zu zeigen, wie man Hercule verwendet – https://github.com/apiaryio/api.apiblueprint.org

@zdne bei unserer Verwendung von json-schema (über interagent/prmd) teilen wir es entlang von Ressourcenlinien auf und erzwingen im Grunde eine bestimmte Verzeichnisstruktur, um Einschlüsse zu implizieren (mehr oder weniger baut es ein Top-Level-Schema auf, das alle Dinge im Verzeichnis als enthält Unterschemata, also verändert es Ebenen von Dingen). Dies ist offensichtlich ziemlich spezialisiert auf das, was wir tun, und in Ihrem Fall nicht besonders geeignet, aber wir wollten unsere Erfahrung teilen. Im Vergleich dazu scheint Transklusion viel eleganter/flexibler zu sein, aber es wäre definitiv schön, auch einige einfache Mittel zu haben, um ein konsolidiertes Inhaltsverzeichnis/einen Index zu haben. Vielleicht ähnelt das aber dem, was wir getan haben, dh Sie erstellen einen Über-Blueprint, der als dieser Index dient, und fügen dann die darin enthaltenen Sub-Blueprints ein/verweisen darauf. Ich sehe das automatisch als schön, aber auch als peinlich, wenn es nicht genau das tut, was Sie wollen. Wie auch immer, lange gesagt, ich würde gerne meine Erfahrungen weiter diskutieren / teilen, wenn das hilfreich wäre.

Wie ist der Status dieser Funktion?
Wir verwenden den Pro-Plan in Apiary.io und wir brauchen diese Funktion

@DavidBM Ich hatte das gleiche Problem. Wie ich das umgangen habe, ist, zwei apiary.apib Dokumente zu haben.

Unkompiliert

apiary-source.apib - eine nicht kompilierte Quelle, die von der Include -Funktion Gebrauch macht

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

# Hello World

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

Kompilieren

Sie können einfach ausführen:

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

Ihr apiary.apib sollte jetzt den Inhalt von blueprint/posts.apib enthalten.

Hallo danke! Ja, aber dann können Sie die Dokumente in apiary.io nicht bearbeiten

Wir hatten bereits die angepasste Lösung mit Hercule, aber der Sinn des Bezahlens von Apiary Pro für uns besteht darin, die Produktmanager die Dokumentation aktualisieren zu lassen, ohne Git eingeben zu müssen. Ich befürchte, dass dies ein völliger Blocker für uns ist und wir den Vertrag mit Apiary kündigen werden, wenn dies nicht gelöst wird.

Ich würde nicht erwarten, dass dies in diesem Zustand ist, nachdem ich Hercule und andere Tools so lange zur Verfügung hatte.

Das ist sehr sehr enttäuschend :(

Hallo zusammen, es tut mir leid, dass ich zu spät komme und wieder aufmache und alte Sachen ausgrabe. Wenn dies nicht der richtige Ort ist, verzeihen Sie mir bitte. Aber bei einer Recherche zur Entwicklung von Blaupausen-Mocks habe ich diese Diskussion gefunden, und dies ist die nächste, die ich bisher finden konnte.

Ich habe Schwierigkeiten, meine Antworten nach Modell aufzuteilen :(. Ist es nicht möglich, ein Modell in einen anderen Ordner zu verweisen?
Ich möchte alle meine Anforderungen in meinem Blueprints-Ordner haben und zum Beispiel in einem separaten Modellordner alle meine Entitätsmodelle (MSON/MD/JSON/was auch immer Dateien, die passen), um sie einfach in verschiedenen Antworten wiederzuverwenden. Hat jemand damit Erfolg?

Es wäre wirklich toll, wenn dieses Thema etwas Aufmerksamkeit bekommen würde. Wir haben 26.000 Zeilen in unserem API-Blueprint, was die Verwaltung unglaublich schwierig macht

Wir implementieren Vertragstests mit Dredd und wir verwenden Aglio, aber es wäre großartig, wenn dies hinzugefügt würde, damit wir dies nicht tun müssten

Einer der Gründe ist, dass wir viel am Design iterieren :) Als diese Ausgabe geöffnet wurde, gab es kein MSON und wir sind immer noch hin- und hergerissen zwischen Transklusionen und Referenzen.

Aber fürs Protokoll, was sind Ihre Bedürfnisse dort? Ist es nur die Verwaltung mehrerer Dateien und das Kompilieren eines einzelnen Dokuments als Ergebnis oder sprechen Sie auch von der Wiederverwendbarkeit von Modellen und dem Teilen von Teilen über mehrere API-Beschreibungsdokumente hinweg?

Einer der Gründe ist, dass wir viel am Design iterieren :) Als diese Ausgabe geöffnet wurde, gab es kein MSON und wir sind immer noch hin- und hergerissen zwischen Transklusionen und Referenzen.

Aber fürs Protokoll, was sind Ihre Bedürfnisse dort? Ist es nur die Verwaltung mehrerer Dateien und das Kompilieren eines einzelnen Dokuments als Ergebnis oder sprechen Sie auch von der Wiederverwendbarkeit von Modellen und dem Teilen von Teilen über mehrere API-Beschreibungsdokumente hinweg?

Wir haben eine Standardantwort, die von einer Reihe unserer Endpunkte kommt. Wir möchten dies an einem einzigen Ort definieren können, in der Nähe der Bibliothek, in der es untergebracht ist, und es dann importieren, wo immer wir damit reagieren müssen.