Преобразование спецификации Swagger Документация JSON для HTML

Для некоторых API REST, написанных на PHP, мне было предложено создать документацию Swagger, и поскольку я не знал о том, способ добавления аннотаций к существующим API и создания такой документации, я использовал этот редактор для создания некоторых на данный момент.

Я сохранил файлы JSON и YAML, созданные с помощью этого редактора, и теперь мне нужно создать окончательную интерактивную документацию Swagger (это утверждение может показаться наивным и неопределенным). Может кто-нибудь, пожалуйста, дайте мне знать, как я могу преобразовать файл спецификации Swagger JSON в фактическую документацию Swagger? Я на платформе Windows и ничего не знаю о Ant/Maven.

Ответ 1

Меня не устраивало swagger-codegen, когда я искал инструмент для этого, поэтому я написал свой собственный. Посмотрите bootprint-swagger

Основная цель по сравнению с swagger-codegen заключается в том, чтобы обеспечить легкую настройку (хотя вам понадобятся nodejs). И вам должно быть легко адаптировать стили и шаблоны к вашим собственным потребностям, что является основной функциональностью bootprint -project

Ответ 2

Смотрите проект swagger-api/swagger-codegen на GitHub; в проекте README показано, как использовать его для генерации статического HTML. См. Создание статической документации api.

Если вы хотите просмотреть swagger.json, вы можете установить интерфейс Swagger и запустить его. Вы просто развертываете его на веб-сервере (папка dist после клонирования репо из GitHub) и просматриваете интерфейс Swagger в своем браузере. Это приложение для JavaScript.

Ответ 3

Отъезд pretty-swag

Он имеет

Аналогичный вид Swagger-Editor правая панель
Поиск/Фильтр
Сфотографирование схемы
Live Feedback
Вывод в виде одного файла html

Я смотрел редактор Swagger и думал, что он может экспортировать область предварительного просмотра, но оказалось, что это невозможно. Поэтому я написал свою собственную версию.

Полное раскрытие информации: я являюсь автором этого инструмента.

Ответ 4

Вы также можете скачать swagger ui из: https://github.com/swagger-api/swagger-ui, возьмите папку dist, измените index.html: измените конструктор

const ui = SwaggerUIBundle({
    url: ...,

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

теперь папка dist содержит все, что вам нужно, и может быть распределена как

Ответ 5

Посмотрите на эту ссылку: http://zircote.com/swagger-php/installation.html

Загрузить файл phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Установить Composer https://getcomposer.org/download/
Сделать композитор .json
Clone swagger-php/library
Clone swagger-ui/library
Сделать классы PHP и модели PHP для API
Выполнить файл PHP для генерации json
Укажите путь json в api-doc.json
Укажите путь api-doc.json в index.php внутри папки swagger-ui dist

Если вам нужна дополнительная помощь, пожалуйста, не стесняйтесь спрашивать.

Ответ 6

Все было слишком сложно или плохо документировано, поэтому я решил это с помощью простого script swagger-yaml-to-html.py, который работает следующим образом

python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html

Это для YAML, но изменение его для работы с JSON также тривиально.