Slate vs Swagger - Który jest lepszy i który ma więcej opcji?

Question

Muszę udokumentować moje API. Muszę użyć jednego z nich Slate lub Swagger. Chcę wiedzieć, który z nich ma więcej opcji, zalet i wad, który jest lepszy.

Answer 1

Swagger i Slate służą do dwóch różnych celów. Swagger jest próbą standaryzowanego sposobu opisywania REST API (podobny na przykład do ApiBlueprint)

Swagger jest oparty format JSON definicja API, które pozwala na opis REST API.

~ API Design Tooling From Swagger

Slate, z drugiej strony jest to dość tematu do pisania ładnych docs API.

1. Obaj nie wykluczają się wzajemnie
2. Idealnie należy wygenerować dokumentację łupków z Swagger Opis API

Celem Swagger jest zapewnienie standardu, na której inni mogą budować bogate oprzyrządowanie (na przykład: dokumentacja, eksploratory interfejsu API, serwery próbne, generowanie kodu, narzędzia testowe itp.). Patrz, na przykład: Swagger Tooling

Więcej na pytanie: niektóre Slate oprzyrządowanie do puszyć:

• Oto link to a Slate themed swagger UI
• Oto projekt, który generates Slate docs based on your Swagger definition

więc dwa są nie wykluczając się nawzajem, ale na twoje bezpośrednie pytanie: Wdrożenie Swaggera da ci więcej opcji i większą elastyczność (było również umiejętnością generowania dokumentacji Slate).

Answer 2

Z mojego punktu widzenia narzędzia te mają bardzo różne cele. Swagger to język opisu, a łupek służy tylko do dokumentacji.

Użyłem kreatora, aby utworzyć opis, z którego mogę automatycznie generować różnych klientów dla mojego API, a nawet autogenerować dokumentację.

Można również utworzyć Markdown ze specyfikacji swagger i użyć tych znaczników w Slate. [1]

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

Answer 3

O Slate:
- Szablon dokumentacji API/Framework
- wygląda dobrze
- łatwość użycia
- Podświetlanie składni
- Język Specjalny - Zakładka
- Wyszukiwanie strony
- 3 konfiguracje w kolumnach z możliwością personalizacji
- Możemy stworzyć tabelę
- Przewijalne linki do każdego blokuje/metod/Nagłówki
- Alert Instrument [3 rodzaje] - ostrzeżenie, sukces, zawiadomienie
- Stoły kodów błędów HTTP
- Markdown składnia
- Możemy użyć logotypów
- Demo

O Swagger:
- To daje nam dostęp do API wewnątrz samego Dokumenty, gdzie możemy sprawdzić odpowiedź dla każdego konkretnego wniosku.
- Daje jasny obraz interfejsu API odpowiadający jego parametrami i opcjami. - YAML Format oparty
- Nie nadaje się do hipermedialnej API
- Nie ma narzędzi Design for Swagger
- Odpowiedzi są w formacie XML lub JSON
- Swagger JS - biblioteka JavaScript, aby połączyć się z obsługą API Swagger poprzez przeglądarkę lub nodejs
- swagger węzła express - moduł swagger dla node.js wyraźnej modułu
- ma swagger interfejsu ramy
- Demo

Answer 4

dokonać łupek kolby (https://github.com/AhnSeongHyun/slate-flask) w oparciu o pytona kolbie.

cechy:

• plik konfiguracyjny (config.json): Ustaw tytuł, na przykład język programowania kodów wykorzystujących bazę config.json na JSON format. Ustaw także ścieżkę dokumentów API i spis treści (spis treści).

• Obsługa dokumentów Multi-API: Original Slate obsługuje jeden dokument API oparty na formacie Markdown.Ale tablica typu "slate-flask" obsługuje dokumenty multi-API dla efektywnego zarządzania i ilości dokumentów przy użyciu TOC (index.json).

• Obsługa dynamicznych zmian dokumentów: Możesz odzwierciedlić zmiany dokumentów API bez restartowania serwera. Po odświeżeniu strony internetowej, jeśli istnieją zmiany, należy ponownie załadować dokumenty interfejsu API tabletu. Użytkownicy koncentrują się wyłącznie na pisaniu dokumentów API.