Мне нужно документировать мои API. Я должен использовать любой из них Slate Или Swagger. Я хочу знать, у кого есть больше вариантов, плюсов и минусов, которые лучше.Slate vs Swagger - что лучше и у кого больше вариантов?
Swagger and Slate служат для двух целей. Сваггер представляет собой попытку стандартизированным способом описания RESTful API (аналогично, например, ApiBlueprint)
Сваггер представляет собой формат на основе JSON API, определение, что позволяет для описания REST API.
~ API Design Tooling From Swagger
Slate, с другой стороны, это довольно тема для написания хорошей документации API.
Целью Swagger является создание стандарта, на котором другие могут построить обширный набор инструментов (например: документация, исследователи API, макеты серверов, генерация кода, утилиты тестирования и т. д.). См, например: Swagger Tooling
Далее на ваш вопрос: Некоторые Slate оснастки для чванства:
Так два не взаимоисключающим, а вашим прямым вопросом: реализация Swagger предоставит вам больше возможностей и большую гибкость (хорошо также, как и возможность генерации документации Slate).
С моей точки зрения, эти инструменты имеют совершенно разные цели. Swagger - это язык описания, а сланец - только для документации.
Я использовал swagger для создания описания n, из которого я могу автогенерировать разные клиенты для моего API, даже автогенерировать документацию.
Вы также можете создать Markdown из спецификации swagger и использовать эти уценки в Slate. [1]
Спасибо за ваш ответ @Neoecos. Я уже начал документировать использование Swagger. –
@ SaribanD'Cl, если ответ был полезен, пожалуйста, примите ответ greeen ✓ – Neoecos
О Slate:
- API документация Шаблон/Framework
- выглядит хорошо
- простота использования
- подсветка синтаксиса
- Язык Specific - Tabbed
- Поиск по страницам
- 3-х этажный настраиваемый макет
- Мы можем создать таблицу
- прокрутка ссылки на каждый блоки/методы/заголовки
- оповещения об объекте [3 вида] - предупреждение, успех, уведомление
- Таблицы для кодов ошибок HTTP
- Markdown синтаксис
- Мы можем использовать логотип сайта
- Demo
О Swagger:
- Это дает нам доступ API внутри самой документации, где мы можем проверить ответ для любого конкретного запроса.
- Он дает четкое представление об API, отвечающем параметрами и параметрами. - YAML формат на основе
- Не подходит для гипермедиа API
- Там нет Конструкция оснастки для Swagger
- Ответы в XML или JSON
- Кураж JS - JavaScript библиотека для подключения к чванство с поддержкой API, с помощью браузера или nodejs
- Swagger Node Express - модуль Swagger для Node.js экспресс модуля
- имеет структуру чванство UI
- Demo
я сделать шифер-колбу (https://github.com/AhnSeongHyun/slate-flask) на основе питона-колбы.
особенности:
файла конфигурации (config.json): Установить название, язык программирования, например, с использованием кодов config.json базы на JSON формате. Также укажите путь к документам API и TOC (оглавление).
Поддержка документов Multi-API: Оригинальный сланец поддерживает один документ API на основе формата Markdown.Но слайд-фляга поддерживает документы с несколькими API для эффективного управления и количества документов с использованием TOC (index.json).
Поддержка динамических изменений документов: вы можете отражать изменения документов API без перезапуска сервера. Когда обновление веб-страницы, если существуют изменения, перезагружает документы API сланцевой фляги. Пользователям уделяется основное внимание написанию документов API.
Swagger2Slate больше не поддерживается и, кажется, имеет несколько нерешенных проблем. https://github.com/mermade/widdershins - это спецификация Swagger/OpenApi, основанная на Node.js для конвертера меток Slate. Раскрытие информации, я автор. – MikeRalphson
Даже с различными целями hatcommunity переключился с чванства на уклоны, например: http://forum.hatcommunity.org/t/api-documentation-publishing-slate-vs-swagger/69 – gandra404