Как создать статический HTML-файл из документации Swagger?

Я создал Swagger документацию с yaml файл под:

 api/swagger/swagger.yaml

Теперь я хочу поделиться статическим html-документом с его определением, но в проекте swagger было заявлено, что они вообще не планируют поддерживать html-генерацию.

Как я могу создать статический HTML-файл из проекта Swagger?

Источник

7 ответов

Самый простой способ, который я могу придумать, - это использовать Swagger Editor:

  1. Перейти к: https://editor.swagger.io/
  2. Нажмите "Файл" в верхней строке меню и выберите "Импорт файла"
  3. После импорта нажмите "Создать клиент" в верхней строке меню, а затем выберите "HTML" или "HTML2" для создания статической документации HTML.

editor.swagger.io использует generator.swagger.io для генерации API-клиентов, заглушек и документации сервера, а generator.swagger.io работает на основе проекта с открытым исходным кодом Swagger Codegen.

Источник
  1. Загрузите https://github.com/swagger-api/swagger-ui - интересующая папка " dist"
  2. Скопируйте ваш Swagger JSON в папку dist
  3. Откройте index.html и измените значение URL внутри тега в нижней части файла на ./swagger.json (или как там называется ваш чванливый json) (см. здесь)
  4. Хост онлайн! (или запустить локальный сервер для просмотра вывода).
Источник

Существует swagger2markup-cli, который может генерировать статический adoc файл.

Убедитесь, что у вас установлена ​​среда выполнения Java. (Я использую `Java(TM) SE Runtime Environment (сборка 1.8.0_111-b14)).

Вы берете банку:

 wget https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/1.1.0/swagger2markup-cli-1.1.0.jar

И вы можете генерировать статический adoc с помощью этого через:

java -jar ~/your/path/swagger2markup-cli-1.1.0.jar  help convert  -i api/swagger/swagger.yaml --outputFile static-swagger

Этот файл ADOC может быть преобразован в html подать через asciidoctor:

asciidoctor *.adoc

Вам может понадобиться установить его, так как я использую Ubuntu, я могу через:

sudo apt-get -qq install asciidoctor
Источник

Вы пытаетесь экспортировать его для создания единой документации из разных сервисов? Если да, альтернативой может быть https://github.com/varghgeorge/microservices-single-swagger. Этот простой микросервис springboot покажет всю вашу документацию по swagger (с разных серверов) в одном месте на основе конфигурации YAML.

Источник

Используйте такой HTML-файл, чтобы загрузить определение OpenAPI:

      <!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" type="text/css" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css">

  <title>Your App API v1</title>

<body>

  <div id="your-app-docs" />

  <script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
  <script>

    window.onload = function () {

      const ui = SwaggerUIBundle({
        url: "openapi.yml",
        dom_id: "#your-app-docs",
        deepLinking: true,
      })

    }

  </script>

</body>

</html>

Позже вы можете разместить его локально или использовать службу, такую ​​​​как Netlify, для размещения в Интернете.

Источник

Только что попробовал redocly, получилось довольно круто!
Команда с докером:
docker run --rm -v $PWD:/spec redocly/cli build-docs <your_swagger.yaml>

https://www.npmjs.com/package/@redocly/cli

Источник

Другой ответ предложил Swagger Editor, и это здорово. Однако, чтобы получить один файл для импорта в него:

  1. npm install -g @apidevtools/swagger-cli
  2. swagger-cli bundle openapi.yaml --outfile ./openapi-expanded.json --type json

Приведенная выше команда предполагает, что ваш корневой файл назван openapi.yaml и вам нужен выходной файл JSON openapi-expanded.json: этот JSON - это то, что вы импортируете.

Источник
Другие вопросы по тегам