Slate vs Swagger-что лучше, а какие имеют больше вариантов? [закрытый]

Я должен документировать свои API. Я должен использовать любой из них сланец или чванство. Я хочу знать, какой из них имеет больше вариантов, плюсов и минусов, какой из них лучше.

21
api-doc documentation swagger swagger-editor

4 ответов

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

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

~ API дизайн инструмент от Swagger

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

  1. эти два не являются взаимоисключающими
  2. в идеале, следует генерировать документацию slate из вашего описания API Swagger

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

больше к вашему вопросу: некоторый шифер Оснастки для чванства:

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

38

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

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

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

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

3

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

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

2

Я делаю шифер-фляга(https://github.com/AhnSeongHyun/slate-flask) на основе Python-фляга.

характеристики:

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

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

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

0