⏰️ 寻找下一代版本的Swagger编辑器?
SwaggerEditor现在有两个主要发布渠道:
- SwaggerEditor@4 - 从master分支发布,部署在https://editor.swagger.io/
- SwaggerEditor@5 - 从next分支发布,部署在https://editor-next.swagger.io/
只有SwaggerEditor@5支持OpenAPI 3.1.0。 SwaggerEditor@4不会获得OpenAPI 3.1.0的支持,现在被视为遗留版本。 计划是逐步完全迁移到SwaggerEditor@5,并在未来弃用SwaggerEditor@4。
🕰️ 寻找旧版本的Swagger编辑器? 请参考2.x或3.x分支。
Swagger编辑器允许您在浏览器中编辑OpenAPI API定义(OpenAPI 2.0和OpenAPI 3.0.3) 以JSON或YAML格式,并实时预览文档。 然后可以生成有效的OpenAPI定义,并与完整的Swagger工具(代码生成、文档等)一起使用。
作为一个全新版本,从头开始编写,存在一些已知问题和未实现的功能。查看已知问题部分了解更多详情。
此仓库发布到两个不同的NPM模块:
- swagger-editor是一个传统的npm模块,适用于能够解析依赖项(通过Webpack、Browserify等)的单页应用程序。
- swagger-editor-dist是一个无依赖模块,包含在服务器端项目或无法解析npm模块依赖项的Web项目中使用Swagger编辑器所需的一切。
如果您正在构建单页应用程序,强烈建议使用swagger-editor
,因为swagger-editor-dist
明显更大。
有用的脚本
以下任何脚本都可以通过在项目根目录中键入npm run <脚本名称>
来运行。
开发
脚本名称 | 描述 |
---|---|
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 | 在Node中运行基于Mocha的单元测试。 |
test:unit-jest | 在Node中运行基于Jest的单元测试。 |
e2e | 使用Cypress运行端到端浏览器测试。 |
lint | 运行ESLint测试 |
test:artifact | 在Jest中运行一系列bundle构件测试 |
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 导出为函数 |
本地运行
先决条件
- git,任何版本
- Node.js >=20.3.0和npm >=9.6.7是此仓库运行的最低要求版本,但我们始终建议使用最新版本的Node.js。
$ npm i --legacy-peer-deps
如果您已安装Node.js和npm,可以运行npm start
来启动静态服务器。
否则,您可以直接从文件系统在浏览器中打开index.html
。
如果您想对Swagger编辑器进行代码更改,可以通过npm run dev
启动Webpack热重载开发服务器。
浏览器支持
Swagger编辑器适用于Chrome、Safari、Firefox和Edge的最新版本。
已知问题
为了帮助迁移,以下是3.X版本当前已知的问题。此列表将定期更新,不包括以前版本中未实现的功能。
- Swagger UI的已知问题中列出的所有内容。
- 与代码生成的集成仍然缺失。
Docker
从DockerHub运行镜像
在DockerHub上发布了一个docker镜像。
要使用它,请运行以下命令:
docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor
这将在您机器的80端口上运行Swagger编辑器(以分离模式),因此您可以通过在浏览器中导航到http://localhost
来打开它。
- 您可以提供指向API定义的URL(如果执行某些安全策略如CSP或CORS,可能无法使用):
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
变量指定不同的基本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
变量指定Google Tag Manager ID来跟踪swagger-editor的使用情况。
docker run -d -p 80:8080 -e GTM=GTM-XXXXXX swaggerapi/swagger-editor
您还可以使用以下环境变量自定义 Swagger Editor 使用的不同端点。例如,如果您有自己的 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 Editor 而不使用代码生成功能(生成服务器和生成客户端),可以将上述环境变量设置为 null
(URL_SWAGGER2_CONVERTER=null
)。
本地构建和运行镜像
要在您的机器上使用检出的代码构建和运行 Docker 镜像,请从项目的根目录运行以下命令:
# 安装 npm 包(如果需要)
npm install
# 构建应用
npm run build
# 构建镜像
docker build -t swagger-editor .
# 运行容器
docker run -d -p 80:8080 swagger-editor
然后,您可以在浏览器中导航到 http://localhost
查看应用。
文档
使用旧版本的 React
[!重要] 这里的旧版本特指
React >=17 <18
。
默认情况下,swagger-editor@4 npm 包附带最新版本的 React@18。 可以使用较旧版本的 React 与 swagger-editor@4 npm 包一起使用。
假设我的应用程序集成了 swagger-editor@4 npm 包,并使用 React@17.0.2。
npm
为了告知 swagger-editor@4
npm 包我需要它使用我的 React 版本,我需要使用 npm overrides。
{
"dependencies": {
"react": "=17.0.2",
"react-dom": "=17.0.2"
},
"overrides": {
"swagger-editor": {
"react": "$react",
"react": "$react-dom",
"react-redux": "^8"
}
}
}
[!注意] React 和 ReactDOM 覆盖定义为对依赖项的引用。由于 react-redux@9 仅支持
React >= 18
,我们需要使用 react-redux@8。
yarn
为了告知 swagger-editor@4
npm 包我需要它使用我的特定 React 版本,我需要使用 yarn resolutions。
{
"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 不支持像 npm 那样的别名,如
$react
或$react-dom
。您需要指定确切的版本。
安全联系
请通过发送电子邮件至 security@swagger.io 披露任何与安全相关的问题或漏洞,而不要使用公共问题跟踪器。