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


88

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

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

Может кто-нибудь, дайте мне знать, как я могу преобразовать файл спецификации Swagger JSON в актуальную документацию Swagger?

Я работаю на платформе Windows и ничего не знаю об Ant / Maven.


Я пробовал [ github.com/wordnik/swagger-ui visible ( Swagger UI), но мой json не отображается. отображается только одно предупреждение: «Этот API использует устаревшую версию Swagger! Дополнительную информацию см. на github.com/wordnik/swagger-core/wiki ».
Салил

Ответы:


43

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

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


9
Предупреждение: по состоянию на 11/2016 автор bootprint-swagger, по-видимому, покинул проект. swagger-codegen по-прежнему хорошо поддерживается.
Brent Matzelle

22
Я являюсь автором, и в тексте говорится: «К сожалению, я не смогу разработать новые функции для этого проекта в ближайшем будущем. Но: я, вероятно, смогу обсудить и объединить запросы на включение, и публиковать новые версии ». Вы можете назвать это заброшенным, я бы назвал это «на удержании». Я также приглашаю всех, кто заинтересован в участии в проекте.
Нильс Кнаппмайер

1
Обнаружено, что spectacleгенерирует гораздо более
красивую

После долгой борьбы я нашел этот инструмент очень полезным: api-html
Асфандияр Хан

57

Попробуйте использовать redoc-cli .

Я использовал bootprint-OpenAPI , с помощью которого я генерирующий кучу файлов ( bundle.js, bundle.js.map, index.html, main.cssи main.css.map) , а затем вы можете преобразовать его в один .htmlфайл с помощью HTML-инлайн для создания простого index.htmlфайла.

Затем я обнаружил, что redoc-cli очень прост в использовании, а вывод действительно потрясающий, один красивый файл index.html .

Установка :

npm install -g redoc-cli

Использование :

redoc-cli bundle -o index.html swagger.json

8
Этот инструмент дает действительно самый красивый результат из всех упомянутых инструментов.
Якуб Моравец

1
На данный момент это лучший вариант, и, поскольку мы создаем его для разработчиков, использующих рабочие столы, размер вывода не является проблемой.
milosmns 04

3
Использование прямого имени исполняемого файла не всегда работает, выполнение npx redoc-cli ...более надежно.
Crouching Kitten

2
Очень красивый вывод. Спасибо за предложение.
Сахил Джайн,

1
Это потрясающий инструмент !! Спасибо Викасу за прекрасное предложение, братан !! Определенно лучше и менее неуклюже, чем bootstrap-openapi!
Чатурведи Саураб,

19

Проверить красивую хабар

Оно имеет

  1. Похоже на правую панель Swagger-Editor
  2. Поиск / Фильтр
  3. Складывание схемы
  4. Live Feedback
  5. Вывод в виде одного HTML-файла

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

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


1
Я считаю, что pretty-swag - простой и идеальный инструмент с соответствующими точками входа в интерфейс командной строки и API. Моя единственная жалоба (и та, которая заставила меня вместо этого столкнуться со сложностью swagger-ui) заключалась в том, что он не смог правильно обработать композицию / расширение объекта. Любое использование allOfв документе приводит к возникновению undefinedдаже в простейших сценариях («слияние» одного объекта, что эквивалентно отсутствию использования allOfвообще).
HonoredMule 01

3
Только что развернули allOfдля вас функцию. Проверить это.
TLJ

2
Похоже, что не поддерживает Swagger / OpenAPI V3
SeinopSys

18

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

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

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


Это чистое золото!
Земирко

16

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

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


Спасибо. Моя проблема заключалась в том, что swagger-ui не принимал спецификацию 2.0. Однако это выглядит как простейший ответ, поэтому я приму его (пока).
Салил

Инструменты Swagger все еще развиваются для версии 2.0. Однако я обнаружил, что пользовательский интерфейс Swagger действительно работает с моими файлами 2.0, которые начинаются с «swagger»: «2.0»,
djb

Кроме того, из редактора Swagger вы можете экспортировать спецификацию JSON (не как YAML, а как JSON), и пользовательский интерфейс Swagger должен ее прочитать. (Примечание: swagger.json должен находиться на том же хосте / порту, что и приложение Swagger UI, или вы должны включить CORS; см. README.md в редакторе Swagger на GitHub
djb

14

Я потратил много времени и перепробовал много разных решений - в итоге сделал так:

<html>
    <head>    
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/swagger-ui.css">
        <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
        <script>

            function render() {
                var ui = SwaggerUIBundle({
                    url:  `path/to/my/swagger.yaml`,
                    dom_id: '#swagger-ui',
                    presets: [
                        SwaggerUIBundle.presets.apis,
                        SwaggerUIBundle.SwaggerUIStandalonePreset
                    ]
                });
            }

        </script>
    </head>

    <body onload="render()">
        <div id="swagger-ui"></div>
    </body>
</html>

Вам просто нужно, чтобы путь / к / my / swagger.yaml обслуживался из того же места.
(или используйте заголовки CORS)


Отлично, спасибо! Я использовал <link rel = "stylesheet" href = " petstore.swagger.io/swagger-ui.css "> <script src = " petstore.swagger.io/swagger-ui-bundle.js "></ script >
Erando

1
Я нашел, что это лучшее решение, без установки чего-либо!
KurioZ7

Очень полезно. Вы сэкономили много времени.
кальпеш хуле

7

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

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

в

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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


2

Взгляните на эту ссылку: http://zircote.com/swagger-php/installation.html

  1. Загрузите файл phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
  2. Установите Composer https://getcomposer.org/download/
  3. Сделайте composer.json
  4. Клонировать swagger-php / library
  5. Клонировать swagger-ui / library
  6. Сделайте классы ресурсов и моделей php для API
  7. Запустите файл PHP, чтобы сгенерировать json
  8. Укажите путь json в api-doc.json
  9. Укажите путь к api-doc.json в index.php внутри папки swagger-ui dist

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


1
Есть ли онлайн-редактор (кроме swagger-editor), который может сгенерировать это для меня? Я не хочу аннотировать свои PHP API, если есть более простой способ. Проблема, как я понял, заключается в том, что редактор swagger генерирует спецификацию swagger v2.0, а swagger-ui на данный момент не справляется с этим.
Салил

@Salil, все, что я знаю, это то, что swagger предоставляет собственный онлайн-редактор, то есть editor.swagger.wordnik.com, я не знаю ни одного другого онлайн-редактора, если вы найдете, поделитесь им с нами, спасибо :)
Сайед Раза Mehdi

2

Есть небольшая программа на Java, которая генерирует документы (adoc или md) из файла yaml.

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
        .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
        .withOutputLanguage(Language.DE)
        .build();

Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);

К сожалению, он поддерживает только OpenAPI 2.0, но не OpenAPI 3.0 .


2

Для Swagger API 3.0 генерация клиентского кода Html2 из онлайн-редактора Swagger отлично работает!


1

Я нашел этот инструмент под названием api-html очень полезным. Он создает потрясающий пользовательский интерфейс html5 с множеством возможностей.

Есть варианты для создания онлайн или через инструмент cli .

Вот ссылка на демонстрационную сборку на "api-html": pets-demo

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.