swagger Как сгнерировать HTML страницу c документацией (напр. из yaml)

Предположим, что yaml с информацией о метода вы генерировать уже уже научились и теперь нам надо перегнуть его в html.

Наиболее простым способом является (но не самым быстрым и удобным):

  1. взять сгенерированный yaml
  2. добавить его слева в область кода на https://editor.swagger.io/
  3. и далее из главного меню:
    Generate Client -> html2

    качаем получившийся html и наслаждаемся)

На локальной машине же можно обойтись без копирования руками в браузер. Рассмотрим этот способ ниже.

swagger-ui -- для отображения HTML документации

swagger-ui можно использовать (рекомендуется) для отображения документации к API в виде HTML.
Чтобы завести эту возможность, делаем следующее:

  1. Качаем последний релиз https://github.com/swagger-api/swagger-u...
  2. Подпапка dist/ - это все что нужно нам для отображения нашей документации (там есть index.html и js, который на ходу умеет парсить описание API, по сути это SPA приложение) -- скопируйте все dist/ содержимое в нужную вам директорию.
  3. По умолчанию будет разбираться файл из сети, чтобы указать путь к нашему файлу, придется положить его на том же уровне, что и index.html (или копируем руками или меняем путь при его генерации)
    Откроем для редактирования index.html и укажем новый путь:
    const ui = SwaggerUIBundle({
            url: "./openapi.yaml", // новый путь ("рядом с index.html")
    

Все! Теперь можно открыть index.html (можно даже не создавать виртуальный хост) и посмотреть что получилось ;)

swagger-codegen Генерация на локальной машине

Далее рассмотрим способ с использованием swagger-codegen, этот проект позволяет генерировать код по вашему описанию API, в том числе и html (хотя на момент написания это решение в отношении html уступает числу поддерживаемых инструкций и красоте отображения, если сравнивать со swagger-ui).
Рассмотрим пример с использованием консольной программы.

  1. Скачайте последнюю его версию, например просто на джар архив в папку

    wget http://central.maven.org/maven2/io/swagg... -O swagger-codegen-cli.jar

    -- перед адресом не забудьте добавить

    ВНИМАНИЕ: позже оказалось, что последней версии с очередными исправлениями на сайте было, тогда пришлось клонировать репозиторий и собирать его с помощью maven-а, как написано тут:

    git clone https://github.com/swagger-api/swagger-codegen
    cd swagger-codegen
    mvn clean package
    java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate \
    -i http://petstore.swagger.io/v2/swagger.json \
    -l php \
    -o /var/tmp/php_api_client

    -- после чего (по аналогии с тем, что описано далее) использовать jar файл вроде (путь относительно корня папки):

    modules/swagger-codegen-cli/target/swagger-codegen-cli.jar
  2. Далее перейдите в консоли в папку, где лежит ваш только что скаченный swagger-codegen-cli.jar, и выполните команду вида:
    java -jar swagger-codegen-cli.jar generate -i /var/www/myproject/openapi.yaml -l  html2

    где:

    • -i/var/www/myproject/openapi.yaml -- путь к yaml-файлу (у вас он скорее всего будет другим)), на основе которого будет построеhtml
    • -l html2 -- указание языка сборки, на то что надо собирать результат в виде html описания (версия 2 более красивая и продвинуто оформленная).