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-ui (напр. через докер) см. тут: https://github.com/swagger-api/swagger-u...

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

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

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

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

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

   • список всех версий можно глянуть тут (в примере выше мы качали swagger-codegen-cli-3.0.0-rc1.jar ): http://central.maven.org/maven2/io/swagg...

   ВНИМАНИЕ: позже оказалось, что последней версии с очередными исправлениями на сайте было, тогда пришлось клонировать репозиторий и собирать его с помощью 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 более красивая и продвинуто оформленная).