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

Question 1

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

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

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

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

Question 2

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

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

Question 3

Попробуйте использовать 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

Question 4

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

Оно имеет

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

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

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

Question 5

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

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

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

Question 6

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

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

Question 7

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

<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)

Question 8

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

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

в

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

Question 9

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

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

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

Question 10

Есть небольшая программа на 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 .

Question 11

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

Question 12

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

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

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

Answer 1

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

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

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

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

Answer 2

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

Салил

Answer 3

43

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

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

Нильс Кнаппмайер
источник

9

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

Brent Matzelle

22

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

Нильс Кнаппмайер

1

Обнаружено, что spectacleгенерирует гораздо более

красивую

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

Асфандияр Хан

Answer 4

9

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

Brent Matzelle

Answer 5

22

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

Нильс Кнаппмайер

Answer 6

1

Обнаружено, что spectacleгенерирует гораздо более

красивую

Answer 7

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

Асфандияр Хан

Answer 8

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!

Чатурведи Саураб,

Answer 9

8

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

Якуб Моравец

Answer 10

1

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

milosmns 04

Answer 11

3

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

Crouching Kitten

Answer 12

2

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

Сахил Джайн,

Answer 13

1

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

Чатурведи Саураб,

Answer 14

19

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

Оно имеет

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

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

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

TLJ
источник

1

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

HonoredMule 01

3

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

TLJ

2

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

SeinopSys

Answer 15

1

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

HonoredMule 01

Answer 16

3

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

TLJ

Answer 17

2

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

SeinopSys

Answer 18

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

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

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

Answer 19

Это чистое золото!

Земирко

Answer 20

16

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

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

djb
источник

Спасибо. Моя проблема заключалась в том, что 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

Answer 21

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

Салил

Answer 22

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

djb

Answer 23

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

djb

Answer 24

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

<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)

Answer 25

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

Erando

Answer 26

1

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

KurioZ7

Answer 27

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

кальпеш хуле

Answer 28

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

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

в

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

Answer 29

2

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

Загрузите файл phar https://github.com/zircote/swagger-php/blob/master/swagger.phar
Установите Composer https://getcomposer.org/download/
Сделайте composer.json
Клонировать swagger-php / library
Клонировать swagger-ui / library
Сделайте классы ресурсов и моделей php для API
Запустите файл PHP, чтобы сгенерировать json
Укажите путь json в api-doc.json
Укажите путь к 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

Answer 30

1

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

Салил

Answer 31

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

Сайед Раза Mehdi

Answer 32

Есть небольшая программа на 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 .

Answer 33

2

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

Кумар С
источник

Answer 34

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

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

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

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

Ответы: