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

⏰️ 寻找下一代版本的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"
  }
}