<img src="https://yellow-cdn.veclightyear.com/0a4dffa0/7632e194-24d8-4027-93d1-81dabe8594bd.png" height="80">

⏰️ 寻找下一代版本的Swagger编辑器？

SwaggerEditor现在有两个主要发布渠道：

1. SwaggerEditor@4 - 从master分支发布，部署在https://editor.swagger.io/
2. 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 查看应用。

文档

• 导入您的 OpenAPI 文档

• 贡献

使用旧版本的 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 披露任何与安全相关的问题或漏洞，而不要使用公共问题跟踪器。