Создание статических документов с помощью swagger

Есть ли способ создания статической документации для swagger 2.0? Возможно, как "предварительный просмотр" на editor.swagger.io.

Мне нужно получить статические html файлы, чтобы я мог включать их в некоторые статические документы.

До сих пор я не нашел способ сделать это. Я вижу, что есть статические документы для swagger-codegens но это работает только для swagger <= 1.2.

Ответы

Ответ 1

Используйте swagger-codegen:

swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>

Если вы решили настроить шаблон HTML:

  1. Клонируем проект swagger-codegen из github
  2. Скопируйте папку modules/swagger-codegen/src/main/resources/htmlDocs2 в другое место, например: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates
  3. Измените шаблоны .mustache в ~/templates чтобы они соответствовали вашим требованиям.
  4. Выполнить: swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> для <templates path> должен быть ~/templates в приведенном выше примере,

Ответ 2

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

npm install spectacle-docs, если вы хотите поместить script в package.json или npm install -g spectacle-docs, если он должен быть доступен везде.

Затем вы можете просто запустить spectacle spec.yaml, с настройками для создания в конкретный каталог, запустить сервер и/или просмотреть спецификацию и обновить по мере необходимости.

Ответ 5

Вы можете использовать:

  • swagger-ui: просто git клонировать проект и копировать JSON в базовый каталог
  • swagger-codegen

Ответ 6

"static" docs может означать несколько вещей.

Если вы ищете интерактивный дисплей (например, предварительный просмотр редактора), у вас есть swagger-ui (https://github.com/swagger-api/swagger-ui).

Код в кодеге, который делает более статические документы (без кнопки "Попробовать сейчас", например) еще не реализован для 2.0, хотя должен быть доступен в ближайшие несколько недель.

Ответ 7

Я использовал процедуру, описанную здесь http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven.

Он использует Maven для генерации статической документации, и результат вполне читабелен. Похоже, что он легко настраивается и расширяется, хотя я еще не пробовал.

Ответ 8

Нажмите на предварительный просмотр документов, используйте chrome addon "Save Page WE" (щелкните правой кнопкой мыши на странице → "сохранить страницу we"), в результате вы получите один HTML файл (его нельзя кликнуть, поэтому вам нужно щелкнуть все, что вы хотите видеть).

Ответ 9

Наличие вашей спецификации OpenAPI/Swagger в spec.json (также может быть в YAML) с использованием статической сборки образа Spectacle Docker может быть сгенерировано следующим образом:

mkdir -m 777 build && docker run --rm \
    -v 'pwd'/build:/tmp/build \
    -v 'pwd'/spec.json:/tmp/spec.json \
    sourcey/spectacle \
    spectacle -t /tmp/build /tmp/spec.json

Ответ 10

Я обычно делаю это с https://editor.swagger.io/. Нет установки или что-либо требуется.

Скопируйте ваш yml файл в редактор и выберите "Generate Client> html2", и он будет генерировать статические html файлы в zip файле.

Ответ 11

Вы можете использовать команду swagger-codegen, как уже упоминали другие, но вывод, который вы получаете от использования -l html или -l html2, не является интерактивным, как интерфейс Swagger.

Чтобы получить интерактивную статическую страницу, например пользовательский интерфейс Swagger, выполните следующие действия:

Установить

  • Перейдите на https://github.com/swagger-api/swagger-ui/releases и загрузите последний выпуск в виде файла .zip.
  • Разархивируйте файл и скопируйте все в папке ./dist в каталог, в который вы хотите, чтобы веб-сервер работал. Например, Gitlab Pages необходимо, чтобы он находился в папке ./public в вашем хранилище.
  • Скопируйте файл swagger.yml в папку ./public.
  • Откройте файл. /public/index.html и обновите URL-адрес, по которому файл веб-сервера будет размещен на веб-сервере. Для локального сервера это может быть так: url: "http://localhost:8000/swagger.yml

Тест

Чтобы проверить это, вы можете запустить простой HTTP-сервер, используя python3.

python3 -m http.server 8000 --directory public

Откройте http://localhost:8000/ и проверьте это!

Ответ 13

Включите зависимость для чванства в вашей поме.

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.4.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.4.0</version>
        </dependency>

И попробуйте нажать → https://editor.swagger.io/