Для некоторых API REST, написанных на PHP, мне было предложено создать документацию Swagger, и поскольку я не знал о том, способ добавления аннотаций к существующим API и создания такой документации, я использовал этот редактор для создания некоторых на данный момент.
Я сохранил файлы JSON и YAML, созданные с помощью этого редактора, и теперь мне нужно создать окончательную интерактивную документацию Swagger (это утверждение может показаться наивным и неопределенным). Может кто-нибудь, пожалуйста, дайте мне знать, как я могу преобразовать файл спецификации Swagger JSON в фактическую документацию Swagger? Я на платформе Windows и ничего не знаю о Ant/Maven.
Меня не устраивало swagger-codegen, когда я искал инструмент для этого, поэтому я написал свой собственный. Посмотрите bootprint-swagger
Основная цель по сравнению с swagger-codegen заключается в том, чтобы обеспечить легкую настройку (хотя вам понадобятся nodejs).
И вам должно быть легко адаптировать стили и шаблоны к вашим собственным потребностям, что является основной функциональностью bootprint -project
Смотрите проект swagger-api/swagger-codegen на GitHub; в проекте README показано, как использовать его для генерации статического HTML. См. Создание статической документации api.
Если вы хотите просмотреть swagger.json, вы можете установить интерфейс Swagger и запустить его. Вы просто развертываете его на веб-сервере (папка dist после клонирования репо из GitHub) и просматриваете интерфейс Swagger в своем браузере. Это приложение для JavaScript.
Отъезд pretty-swag
Он имеет
Я смотрел редактор Swagger и думал, что он может экспортировать область предварительного просмотра, но оказалось, что это невозможно. Поэтому я написал свою собственную версию.
Полное раскрытие информации: я являюсь автором этого инструмента.
Вы также можете скачать swagger ui из: https://github.com/swagger-api/swagger-ui, возьмите папку dist, измените index.html: измените конструктор
const ui = SwaggerUIBundle({
url: ...,
в
const ui = SwaggerUIBundle({
spec: YOUR_JSON,
теперь папка dist содержит все, что вам нужно, и может быть распределена как
Посмотрите на эту ссылку: http://zircote.com/swagger-php/installation.html
Если вам нужна дополнительная помощь, пожалуйста, не стесняйтесь спрашивать.
Все было слишком сложно или плохо документировано, поэтому я решил это с помощью простого script swagger-yaml-to-html.py, который работает следующим образом
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
Это для YAML, но изменение его для работы с JSON также тривиально.