Есть ли способ создания статической документации для swagger 2.0? Возможно, как "предварительный просмотр" на editor.swagger.io.
Мне нужно получить статические html файлы, чтобы я мог включать их в некоторые статические документы.
До сих пор я не нашел способ сделать это. Я вижу, что есть статические документы для swagger-codegens но это работает только для swagger <= 1.2.
swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location>
modules/swagger-codegen/src/main/resources/htmlDocs2 в другое место, например: cp -R modules/swagger-codegen/src/main/resources/htmlDocs2 ~/templates.mustache в ~/templates чтобы они соответствовали вашим требованиям.swagger-codegen generate -i <path to your swagger file> -l html2 -o <path to output location> -t <templates path> для <templates path> должен быть ~/templates в приведенном выше примере,Если вы просто хотите создать статические документы прямолинейно, рассмотрите Spectacle.
npm install spectacle-docs, если вы хотите поместить script в package.json или npm install -g spectacle-docs, если он должен быть доступен везде.
Затем вы можете просто запустить spectacle spec.yaml, с настройками для создания в конкретный каталог, запустить сервер и/или просмотреть спецификацию и обновить по мере необходимости.
Статические документы в версии 2.0 реализованы для версии 2.0. см. здесь. /bin/static -docs.sh:
https://github.com/swagger-api/swagger-codegen/tree/master/bin
Если вы специально ищете Swagger 2.0, я хотел бы указать вам на мой ответ в Преобразование спецификации Swagger JSON в HTML-документацию , хотя я считаю, что Swagger-Codegen теперь поддерживает Swagger 2.0.
Вы можете использовать:
"static" docs может означать несколько вещей.
Если вы ищете интерактивный дисплей (например, предварительный просмотр редактора), у вас есть swagger-ui (https://github.com/swagger-api/swagger-ui).
Код в кодеге, который делает более статические документы (без кнопки "Попробовать сейчас", например) еще не реализован для 2.0, хотя должен быть доступен в ближайшие несколько недель.
Я использовал процедуру, описанную здесь http://ics.upjs.sk/~novotnyr/blog/2156/create-html-documentation-from-swagger-via-maven.
Он использует Maven для генерации статической документации, и результат вполне читабелен. Похоже, что он легко настраивается и расширяется, хотя я еще не пробовал.
Нажмите на предварительный просмотр документов, используйте chrome addon "Save Page WE" (щелкните правой кнопкой мыши на странице → "сохранить страницу we"), в результате вы получите один HTML файл (его нельзя кликнуть, поэтому вам нужно щелкнуть все, что вы хотите видеть).
Наличие вашей спецификации 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
Я обычно делаю это с https://editor.swagger.io/. Нет установки или что-либо требуется.
Скопируйте ваш yml файл в редактор и выберите "Generate Client> html2", и он будет генерировать статические html файлы в zip файле.
Вы можете использовать команду swagger-codegen, как уже упоминали другие, но вывод, который вы получаете от использования -l html или -l html2, не является интерактивным, как интерфейс Swagger.
Чтобы получить интерактивную статическую страницу, например пользовательский интерфейс Swagger, выполните следующие действия:
url: "http://localhost:8000/swagger.ymlЧтобы проверить это, вы можете запустить простой HTTP-сервер, используя python3.
python3 -m http.server 8000 --directory public
Откройте http://localhost:8000/ и проверьте это!
Вы можете рассмотреть возможность использования ReDoc, который поддерживает OpenAPI/Swagger 2.0 и 3.0. Примеры:
Включите зависимость для чванства в вашей поме.
<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/