Ich muss meine APIs dokumentieren. Ich muss einen von ihnen verwenden Slate Oder Swagger. Ich möchte wissen, welche mehr Optionen, Vor- und Nachteile, welche besser ist.Slate vs Swagger - Was ist besser und welche haben mehr Optionen?
Antwort
Swagger und Slate dienen zwei verschiedenen Zwecken. Swagger ist ein Versuch, eine standardisierte Art und Weise eine RESTful API beschreiben (ähnlich zum Beispiel zu ApiBlueprint)
Swagger ist ein JSON basiertes API Definition Format, das für die Beschreibung des REST APIs erlaubt.
~ API Design Tooling From Swagger
Schiefer, auf der anderen Seite ist ein hübsches Thema für schöne API-Dokumentation zu schreiben.
- Die beiden schließen sich nicht aus
- Idealerweise sollte ein Slate Dokumentation von Ihrem Swagger API-Beschreibung
Ziel Swagger erzeugen ist, einen Standard zu schaffen, auf denen andere umfangreiche Werkzeuge bauen (zum Beispiel: Dokumentation, API-Explorer, Mock-Server, Codegenerierung, Testprogramme usw.). Siehe zum Beispiel: Swagger Tooling
Mehr auf Ihre Frage: Einige Slate Werkzeuge für Prahlerei:
- Hier ist ein link to a Slate themed swagger UI
- Dies ist ein Projekt, das generates Slate docs based on your Swagger definition
So sind die beiden sich nicht gegenseitig ausschließen, aber zu Ihrer direkten Frage: Die Implementierung von Swagger wird Ihnen mehr Optionen und größere Flexibilität geben (war auch die Fähigkeit, Slate-Dokumentation zu generieren).
Aus meiner Sicht haben diese Tools sehr unterschiedliche Zwecke. Swagger ist eine Beschreibungssprache, während Slate nur zur Dokumentation dient.
Ich habe Swagger verwendet, um eine Beschreibung zu erstellen, aus der ich verschiedene Clients für meine API automatisch generieren kann, sogar Dokumentation automatisch erstellen.
Sie können Markdown auch aus der Swagger-Spezifikation erstellen und diese Markdowns in Slate verwenden. [1]
Danke für Ihre Antwort @Neoecos. Ich habe bereits begonnen, mit Swagger zu dokumentieren. –
@ SaribanD'Cl Wenn die Antwort nützlich war, bitte akzeptieren Sie die Antwort greeen ✓ – Neoecos
über Slate:
- API-Dokumentation Template/Rahmen
- sieht gut aus
- einfacher Bedienung
- Syntax-Hervorhebung
- Sprache Specific - Registerkarten
- Seite Suche - 3 columned anpassbare Layout
- Wir können Tabelle
erstellen - Scrollbare Links zu jedem einzelnen Blöcke/Methoden/Überschriften
- Alarm Anlage [3 Arten] - Warnung, Erfolg, Ankündigung
- Tabellen für http-Fehlercodes
- Markdown-Syntax
- Wir können Website nutzen Logo
- Demo
über Swagger:
- Es gibt uns die API-Zugriff innerhalb der Dokumentation selbst, wo wir die Antwort für eine bestimmte Anforderung überprüfen.
- Es gibt ein klares Bild der API reagiert mit ihren Parametern und Optionen. - YAML-basiertes Format
- Nicht
für Hypermedia-API geeignet - Es gibt keine Design-Werkzeuge für Swagger
- Antworten sind in XML oder JSON
- Swagger JS - JavaScript-Bibliothek zu Prahlerei-fähigen APIs über den Browser verbinden oder NodeJS
- Swagger Knoten Express - Swagger Modul für node.js Express Modul
- Es hat Prahlerei UI-Framework
- Demo
I Schiefer-Kolben machen (https://github.com/AhnSeongHyun/slate-flask) auf Basis von python-Kolben.
Features:
Konfigurationsdatei (config.json): Stellen Sie Titel, Sprachenprogrammierung für config.json Basis Beispiel-Codes auf JSON-Format. Legen Sie auch den Pfad der API-Dokumente und des Inhaltsverzeichnisses (Inhaltsverzeichnis) fest.
Unterstützung von Multi-API-Dokumenten: Original Slate unterstützt ein API-Dokument, das auf dem Markdown-Format basiert.Aber slate-flask unterstützt Multi-API-Dokumente für eine effiziente Verwaltung und Menge von Dokumenten mit TOC (index.json).
Dynamische Änderungen von Dokumenten unterstützen: Sie können die Änderungen von API-Dokumenten widerspiegeln, ohne den Server neu zu starten. Wenn die Aktualisierung der Webseite aktualisiert wird, lädt slate-flask API-Dokumente neu. Benutzer konzentrieren sich nur auf das Schreiben von API-Dokumenten.
- 1. Dundas vs ComponentArt welche ist besser
- 2. Was ist besser? private static vs privaten
- 3. Projektreferenz vs. DLL Referenz - Was ist besser?
- 4. accdb vs mdb. Was ist schneller/besser?
- 5. python isinstance vs hasattr vs versuchen/außer: Was ist besser?
- 6. Welche Tabellenstruktur ist besser
- 7. Was ist besser: Wählen Sie vs Threads?
- 8. heroku vs openshift was ist besser PaaS?
- 9. dict() vs {} in Python was ist besser?
- 10. dict() vs {} in Python was ist besser?
- 11. Docker Compose vs. Dockerfile - was ist besser?
- 12. enum vs android @Intdef - welche ist besser optimiert
- 13. Was ist besser: mehr lesbaren Code oder zusätzlichen Speicherplatz im Interpreter für das Einwegobjekt zu haben?
- 14. Checkbox vs Zwei Radio-Tasten - Welche ist mehr verwendbar?
- 15. Welche ist besser Datenbank-Design
- 16. Singleton Pattern - was ist besser?
- 17. Welche Javascript Funktion ist besser?
- 18. Javascript welche Syntax ist besser?
- 19. WPF Rectangle vs Border: Was ist besser für die Leistung?
- 20. 2Dsphere vs 2D-Index: Was ist "besser"/schneller?
- 21. Java-Thread, was ist besser?
- 22. String Ereignisse vs Klassen Ereignisse in L5.2, was ist besser?
- 23. Welche Methode des Bindungskontexts in React (ES6-Klassen) ist besser
- 24. Was ist besser für eine Abhängigkeit: Web Service vs XML?
- 25. PHP - beenden oder zurück, was ist besser?
- 26. Casting (int?) Null vs. new int?() - Was ist besser?
- 27. Was ist besser Params oder Liste
- 28. XEmacs vs Emacs was ist besser für die Programmierung C++
- 29. GraniteDS vs BlazeDS welche ist mehr als die andere?
- 30. Laravel - Antwort :: oder Antwort() - welche ist besser
Swagger2Slate ist nicht mehr gepflegt und scheint einige ausstehende Probleme zu haben. https://github.com/mermade/widdershins ist ein auf Node.js basierender Swagger/OpenApi-Spec-to-Slate-Abzeichnungskonverter. Offenlegung, ich bin der Autor. – MikeRalphson
Auch mit verschiedenen Zwecken hat Hatcommunity von Swagger zu Slant zum Beispiel gewechselt: http://forum.hatcommunity.org/t/api-documentation-publishing-slate-vs-swagger/69 – gandra404