Slate vs Swagger - что лучше и у кого больше вариантов?

Ответ 1

Свадьба и сланец служат двум различным целям. Swagger - это попытка стандартизованного способа описания API RESTful (аналогично, например, ApiBlueprint)

Swagger - это формат определения API на основе JSON, который позволяет описать API REST.

~ API Design Tooling From Swagger

Slate, с другой стороны, представляет собой прекрасную тему для написания приятных документов API.

• Эти два не являются взаимоисключающими
• В идеале, вы должны сгенерировать свою слайдерную документацию из описания Swagger API.

Цель Swagger - предоставить стандарт, на котором другие могут создавать обширные инструменты (например: документация, исследователи API, макеты серверов, генерация кода, утилиты для тестирования и т.д.). См., Например: Инструмент Swagger

Подробнее на ваш вопрос: Некоторые инструменты для шифера для swagger:

• Ниже приведена ссылка на пользовательский интерфейс Swag themed swagger
• Вот проект, который генерирует документы Slate на основе вашего определения Swagger

Таким образом, эти два не являются взаимоисключающими, но к вашему прямому вопросу: реализация Swagger даст вам больше возможностей и большую гибкость (хорошо также, как и возможность генерации документации Slate).

Ответ 2

С моей точки зрения, эти инструменты имеют совершенно разные цели. Swagger - это язык описания, а сланец - только для документации.

Я использовал swagger для создания описания n, из которого я могу автогенерировать разные клиенты для моего API, даже автогенерировать документацию.

Вы также можете создать Markdown из спецификации swagger и использовать эти уценки в Slate. [1]

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

Ответ 3

О слайде:
- Документация API Template/Framework
- выглядит хорошо
- простота использования
- подсветка синтаксиса
- Язык специфический - вкладка
- Поиск страницы
- 3-х столбчатый настраиваемый макет
- Мы можем создать таблицу
- Прокручиваемые ссылки на каждый блок/методы/заголовки
- средство оповещения [3 типа] - предупреждение, успех, уведомление
- Таблицы для кодов ошибок http
- Синтаксис Markdown
- Мы можем использовать логотип сайта
- Демо

О Swagger:
- Он дает нам доступ к API внутри самих документов, где мы можем проверить ответ на любой конкретный запрос.
- Он дает четкое представление об ответах API с их параметрами и параметрами. - формат на основе YAML
- Не подходит для гипермедиа API
- Нет инструментов для проектирования Swagger
- Ответы в XML или JSON
- Swagger JS - библиотека JavaScript для подключения к API с поддержкой swagger через браузер или nodejs
- Swagger Node Express - модуль Swagger для node.js express module
- У него есть интерфейс UI

- Демо

Ответ 4

Я делаю слайд-флягу (https://github.com/AhnSeongHyun/slate-flask) на основе python-колбы.

функции:

• Файл конфигурации (config.json): укажите заголовок, язык программирования, например, коды, используя базу config.json в формате JSON. Также укажите путь к документам API и TOC (оглавление).

• Поддержка документов Multi-API: Оригинальный слайдер поддерживает один документ API на основе формата Markdown. Но slate-flask поддерживает документы с несколькими API для эффективного управления и количества документов с использованием TOC (index.json).

• Поддержка динамических изменений документов: вы можете отражать изменения документов API без перезапуска сервера. Когда обновление веб-страницы, если существуют изменения, перезагружает документы API сланцевой фляги. Пользователи обращают внимание только на запись документов API.