swagger editor
v4.14.0 Released!
⏰️ Ищете версию Swagger Editor нового поколения?
SwaggerEditor теперь выпускается в двух основных каналах выпуска:
Только SwaggerEditor@5 поддерживает OpenAPI 3.1.0. SwaggerEditor@4 не получит поддержку OpenAPI 3.1.0 и на данный момент считается устаревшим. Планируется постоянно полностью переходить на SwaggerEditor@5 и прекратить поддержку SwaggerEditor@4 в будущем.
?️ Ищете старую версию редактора Swagger? Обратитесь к ветвям 2.x или 3.x.
Редактор Swagger позволяет редактировать определения API OpenAPI (OpenAPI 2.0 и OpenAPI 3.0.3) в формате JSON или YAML в браузере, а также просматривать документацию в режиме реального времени. Затем можно сгенерировать действительные определения OpenAPI и использовать их с полным набором инструментов Swagger (генерация кода, документация и т. д.).
Это совершенно новая версия, написанная с нуля, с некоторыми известными проблемами и нереализованными функциями. Дополнительную информацию см. в разделе «Известные проблемы».
Этот репозиторий публикуется в двух разных модулях NPM:
Если вы создаете одностраничное приложение, настоятельно рекомендуется использовать swagger-editor , поскольку swagger-editor-dist значительно больше.
Редактор Swagger использует Scarf для сбора анонимной аналитики установки. Эта аналитика помогает поддерживать сопровождающих эту библиотеку и запускается ТОЛЬКО во время установки. Чтобы отказаться, вы можете установить для поля scarfSettings.enabled значение false в package.json вашего проекта:
// package.json
{
// ...
"scarfSettings": {
"enabled": false
}
// ...
}
Альтернативно вы можете установить для переменной среды SCARF_ANALYTICS значение false как часть среды, в которой устанавливаются ваши пакеты npm, например, SCARF_ANALYTICS=false npm install .
Любой из приведенных ниже сценариев можно запустить, набрав npm run <script name> в корневом каталоге проекта.
| Имя сценария | Описание |
|---|---|
dev | Создайте сервер разработки с горячей перезагрузкой на порту 3200. |
deps-check | Создайте отчет о размере и лицензировании зависимостей редакторов Swagger. |
lint | Сообщайте об ошибках и предупреждениях стиля ESLint. |
lint-errors | Сообщайте об ошибках стиля ESLint без предупреждений. |
lint-fix | Попытайтесь автоматически исправить ошибки стиля. |
watch | Пересоберите основные файлы в /dist при изменении исходного кода. Полезно для npm link . |
| Имя сценария | Описание |
|---|---|
build | Создайте новый набор ресурсов JS и CSS и выведите их в /dist . |
build:bundle | Соберите только swagger-editor-bundle.js (commonJS). |
build:core | Создайте только swagger-editor.(js|css) (commonJS). |
build:standalone | Соберите только swagger-editor-standalone-preset.js (commonJS). |
build:stylesheets | Создайте только swagger-editor.css . |
build:es:bundle | Соберите только swagger-editor-es-bundle.js (es2015). |
build:es:bundle:core | Соберите только swagger-editor-es-bundle-core.js (es2015). |
| Имя сценария | Описание |
|---|---|
test | Запускайте модульные тесты в Node, запускайте сквозные тесты Cypress и запускайте ESLint в режиме только ошибок. |
test:unit-mocha | Запускайте модульные тесты на основе Mocha в Node. |
test:unit-jest | Запускайте модульные тесты на основе Jest в Node. |
e2e | Запускайте сквозные браузерные тесты с помощью Cypress. |
lint | Запустите тест ESLint |
test:artifact | Запустить список тестов артефактов пакета в Jest |
test:artifact:umd:bundle | Запустите модульный тест, который подтверждает экспорт swagger-editor-bundle как функцию. |
test:artifact:es:bundle | Запустите модульный тест, который подтверждает экспорт swagger-editor-es-bundle как функцию. |
test:artifact:es:bundle:core | Запустите модульный тест, который подтверждает экспорт swagger-editor-es-bundle-core как функцию. |
$ npm i --legacy-peer-deps Если у вас установлены Node.js и npm, вы можете запустить npm start , чтобы развернуть статический сервер.
В противном случае вы можете открыть index.html прямо из вашей файловой системы в браузере.
Если вы хотите внести изменения в код в редакторе Swagger, вы можете запустить сервер разработки Webpack с горячей перезагрузкой через npm run dev .
Редактор Swagger работает в последних версиях Chrome, Safari, Firefox и Edge.
Чтобы помочь с миграцией, ниже представлены известные на данный момент проблемы с версией 3.X. Этот список будет регулярно обновляться и не будет включать функции, которые не были реализованы в предыдущих версиях.
В DockerHub опубликован образ докера.
Чтобы использовать это, выполните следующее:
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
При этом редактор Swagger будет запущен (в автономном режиме) на порту 80 на вашем компьютере, поэтому вы сможете открыть его, перейдя по адресу http://localhost в своем браузере.
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" swaggerapi/swagger-editor
json или yaml со своего локального хоста: docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json swaggerapi/swagger-editor
Примечание. Если установлены переменные среды URL и SWAGGER_FILE , URL имеет приоритет, а SWAGGER_FILE игнорируется.
BASE_URL для доступа к приложению — например, если вы хотите, чтобы приложение было доступно по адресу http://localhost/swagger-editor/ : docker run -d -p 80:8080 -e BASE_URL=/swagger-editor swaggerapi/swagger-editor
PORT для доступа к приложению, по умолчанию — 8080 . docker run -d -p 80:80 -e PORT=80 swaggerapi/swagger-editor
GTM для отслеживания использования редактора swagger. docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
Вы также можете настроить различные конечные точки, используемые редактором Swagger, с помощью следующих переменных среды. Например, это может быть полезно, если у вас есть собственный сервер-генератор Swagger:
| Переменная среды | Значение по умолчанию |
|---|---|
URL_SWAGGER2_GENERATOR | https://generator.swagger.io/api/swagger.json |
URL_OAS3_GENERATOR | https://generator3.swagger.io/openapi.json |
URL_SWAGGER2_CONVERTER | https://converter.swagger.io/api/convert |
Если вы хотите запустить редактор Swagger локально без функций Codegen (создать сервер и создать клиент), вы можете установить для вышеуказанных переменных среды значение null ( URL_SWAGGER2_CONVERTER=null ).
Чтобы создать и запустить образ Docker с извлеченным на вашем компьютере кодом, запустите следующую команду из корневого каталога проекта:
# Install npm packages (if needed)
npm install
# Build the app
npm run build
# Build an image
docker build -t swagger-editor .
# Run the container
docker run -d -p 80:8080 swagger-editor
Затем вы можете просмотреть приложение, перейдя по адресу http://localhost в своем браузере.
Импорт документа OpenAPI
Содействие
Важный
В более старых версиях мы специально ссылаемся на React >=17 <18 .
По умолчанию пакет npm swagger-editor@4 поставляется с последней версией React@18. Пакет npm swagger-editor@4 можно использовать со старой версией React.
Допустим, мое приложение интегрируется с пакетом npm swagger-editor@4 и использует [email protected].
Чтобы сообщить пакету npm swagger-editor@4 , что мне нужно, чтобы он использовал мою версию React, мне нужно использовать переопределения npm.
{
"dependencies" : {
"react" : " =17.0.2 " ,
"react-dom" : " =17.0.2 "
},
"overrides" : {
"swagger-editor" : {
"react" : " $react " ,
"react" : " $react-dom " ,
"react-redux" : " ^8 "
}
}
}Примечание
Переопределение React и ReactDOM определяется как ссылка на зависимость. Поскольку act-redux@9 поддерживает только React >= 18 , нам нужно использовать act-redux@8 .
Чтобы сообщить пакету swagger-editor@4 npm, что мне нужно, чтобы он использовал мою конкретную версию React, мне нужно использовать разрешения пряжи.
{
"dependencies" : {
"react" : " 17.0.2 " ,
"react-dom" : " 17.0.2 "
},
"resolutions" : {
"swagger-editor/react" : " 17.0.2 " ,
"swagger-editor/react-dom" : " 17.0.2 " ,
"swagger-editor/react-redux" : " ^8 "
}
}Примечание
Разрешение React и ReactDOM не может быть определено как ссылка на зависимость. К сожалению, Yarn не поддерживает псевдонимы, такие как $react или $react-dom как это делает npm . Вам нужно будет указать точные версии.
Пожалуйста, сообщайте о любых проблемах или уязвимостях, связанных с безопасностью, по электронной почте [email protected] вместо использования общедоступного средства отслеживания проблем.
