跳到内容

Swagger Editor 文档

此页面介绍的是当前的 Swagger Editor。如果您正在寻找 Swagger Editor Next (beta)（又称 SwaggerEditor@5）的文档，请访问 Swagger Editor Next (beta)。

Swagger Editor 是一个开源编辑器，用于在 OpenAPI 规范中设计、定义和文档化 HTTP (RESTful) API。Swagger Editor 的源代码可以在 GitHub 上找到。

GitHub: https://github.com/swagger-api/swagger-editor

只有 Swagger Editor Next 支持 OpenAPI 3.1.0。SwaggerEditor@4 将不再获得 OpenAPI 3.1.0 支持，目前被视为旧版。计划是未来完全迁移到 SwaggerEditor@5 并弃用 SwaggerEditor@4。

在网页上使用编辑器

编辑器可在任何网络浏览器中运行，可本地托管或通过网络访问。

前往网页版

本地运行

先决条件

  • git，任何版本
  • Node.js >=20.3.0 和 npm >=9.6.7 是此仓库运行所需的最低版本，但我们始终建议使用最新版本的 Node.js。
终端窗口
1
 $ npm i --legacy-peer-deps

如果您已安装 Node.js 和 npm，可以运行 npm start 启动静态服务器。

否则，您可以直接在浏览器中从文件系统打开 index.html。

如果您想对 Swagger Editor 进行代码更改，可以通过 npm run dev 启动一个 Webpack 热重载开发服务器。

浏览器支持

Swagger Editor 兼容最新版本的 Chrome、Safari、Firefox 和 Edge。

已知问题

为了帮助迁移，以下是 3.X 已知的当前问题。此列表将定期更新，不包括以前版本中未实现的功能。

有用的脚本

以下任何脚本都可以在项目根目录中通过输入 npm run <script name> 运行。

开发中

脚本名称描述
dev在端口 3200 上启动热重载开发服务器。
deps-check生成 Swagger Editor 依赖项的大小和许可报告。
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 中运行捆绑构件测试列表
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 作为函数导出

Docker

从 DockerHub 运行镜像

Docker 镜像已发布在 docker.swagger.io 注册表。

要使用它，请运行以下命令

1
docker pull docker.swagger.io/swaggerapi/swagger-editor
2
docker run -d -p 80:8080 docker.swagger.io/swaggerapi/swagger-editor

这将在您的机器上以分离模式在端口 80 上运行 Swagger Editor，您可以在浏览器中导航到 http://localhost 打开它。

  • 您可以提供指向 API 定义的 URL（如果强制执行 CSP 或 CORS 等安全策略，则可能无法使用）
1
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" docker.swagger.io/swaggerapi/swagger-editor
  • 您可以从本地主机提供自己的 json 或 yaml 定义文件
1
docker run -d -p 80:8080 -v $(pwd):/tmp -e SWAGGER_FILE=/tmp/swagger.json docker.swagger.io/swaggerapi/swagger-editor

注意：当 URL 和 SWAGGER_FILE 环境变量都设置时，URL 具有优先权，SWAGGER_FILE 被忽略。

  • 您可以通过 BASE_URL 变量指定不同的基础 URL 来访问应用程序——例如，如果您希望应用程序在 http://localhost/swagger-editor/ 可用
1
docker run -d -p 80:8080 -e BASE_URL=/swagger-editor docker.swagger.io/swaggerapi/swagger-editor
  • 您可以通过 PORT 变量指定不同的端口来访问应用程序，默认为 8080。
1
docker run -d -p 80:80 -e PORT=80 docker.swagger.io/swaggerapi/swagger-editor
  • 您可以通过 GTM 变量指定 Google 标签管理器 ID，以跟踪 swagger-editor 的使用情况。
1
docker run -d -p 80:8080 -e GTM=GTM-XXXXXX docker.swagger.io/swaggerapi/swagger-editor

您还可以使用以下环境变量自定义 Swagger Editor 使用的不同端点。例如，如果您有自己的 Swagger 生成器服务器，这会很有用

环境变量默认值
URL_SWAGGER2_GENERATORhttps://generator.swagger.io/api/swagger.json
URL_OAS3_GENERATORhttps://generator3.swagger.io/openapi.json
URL_SWAGGER2_CONVERTERhttps://converter.swagger.io/api/convert

如果您想在不使用 Codegen 功能（生成服务器和生成客户端）的情况下本地运行 Swagger Editor，可以将上述环境变量设置为 null (URL_SWAGGER2_CONVERTER=null)。

本地构建和运行镜像

要使用您机器上签出的代码构建并运行 Docker 镜像，请在项目根目录中运行以下命令

1
# Install npm packages (if needed)
2
npm install
3


4
# Build the app
5
npm run build
6


7
# Build an image
8
docker build -t swagger-editor .
9


10
# Run the container
11
docker run -d -p 80:8080 swagger-editor

然后，您可以在浏览器中导航到 http://localhost 查看应用程序。

文档

使用旧版 React

[!IMPORTANT] 较旧版本特指 React >=17 <18。

默认情况下，swagger-editor@4 npm 包附带最新版本的 React@18。可以使用 swagger-editor@4 npm 包与旧版本 React 配合使用。

假设我的应用程序集成了 swagger-editor@4 npm 包并使用了 React@17.0.2。

npm

为了告知 swagger-editor@4 npm 包我需要它使用我的 React 版本，我需要使用 npm overrides。

1
{
2
  "dependencies": {
3
    "react": "=17.0.2",
4
    "react-dom": "=17.0.2"
5
  },
6
  "overrides": {
7
    "swagger-editor": {
8
      "react": "$react",
9
      "react": "$react-dom",
10
      "react-redux": "^8"
11
    }
12
  }
13
}

[!NOTE] React 和 ReactDOM 的覆盖被定义为对依赖项的引用。由于 react-redux@9 仅支持 React >= 18，因此我们需要使用 react-redux@8。

yarn

为了告知 swagger-editor@4 npm 包我需要它使用我特定的 React 版本，我需要使用 yarn resolutions。

1
{
2
  "dependencies": {
3
    "react": "17.0.2",
4
    "react-dom": "17.0.2"
5
  },
6
  "resolutions": {
7
    "swagger-editor/react": "17.0.2",
8
    "swagger-editor/react-dom": "17.0.2",
9
    "swagger-editor/react-redux": "^8"
10
  }
11
}

[!NOTE] React 和 ReactDOM 的解析不能定义为对依赖项的引用。不幸的是，yarn 不像 npm 那样支持别名，如 $react 或 $react-dom。您需要指定确切的版本。

安全联系方式

请通过电子邮件 security@swagger.io 披露任何与安全相关的问题或漏洞，而不是使用公共问题跟踪器。

匿名分析

Swagger Editor 使用 Scarf 收集匿名安装分析。这些分析有助于支持此库的维护者，并且仅在安装期间运行。要选择退出，您可以将项目的 package.json 中 scarfSettings.enabled 字段设置为 false

package.json
1
{
2
  // ...
3
  "scarfSettings": {
4
    "enabled": false
5
  }
6
  // ...
7
}

或者，您可以在安装 npm 包的环境中将环境变量 SCARF_ANALYTICS 设置为 false，例如 SCARF_ANALYTICS=false npm install。

© . All rights reserved.