Slate vs Swagger - Was ist besser und welche haben mehr Optionen?

Question

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.

Answer 1

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.

1. Die beiden schließen sich nicht aus
2. 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).

Answer 2

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]

[1] https://github.com/RobWin/swagger2markup

Answer 3

ü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

Answer 4

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.