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

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

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

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

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

48
swagger swagger-php yaml

9 ответов

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

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

29

проверить довольно-swag

Это

  1. похожий вид, как Swagger-Редактор правая панель
  2. Поиск / Фильтр
  3. Схема Складывания
  4. Живой Отклик
  5. вывод в виде одного html-файла

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

полный Раскрытие информации: я автор инструмента.

13

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

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

11

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

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

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

7

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

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

на

const ui = SwaggerUIBundle({
    spec: YOUR_JSON,

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

6

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

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

тогда я нашел redoc-cli очень прост в использовании и вывод действительно-2 awesome, a одинокий и красивый индекс.HTML-код.

установка:

npm install -g redoc-cli

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

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

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

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

вам просто нужно иметь path / to / my / swagger.и YAML подается из того же места.
(или использовать заголовки CORS)

3

посмотрите на эту ссылку: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. сделать композитор.в JSON
  4. клон swagger-php / библиотека
  5. клон swagger-ui / библиотека
  6. создание ресурсов и моделей классов php для API
  7. выполните файл PHP для создания json
  8. дайте путь json в api-doc.в JSON
  9. дайте путь api-doc.JSON в индекс.php внутри папки swagger-ui dist

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

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.

0