swagger editor下载 - swagger editor源码下载

swagger editor

其他源码

v4.14.0 Released!

下载

⏰️ 正在寻找下一代版本的 Swagger Editor？

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

SwaggerEditor@4 - 从 master 分支发布并部署在 https://editor.swagger.io/
SwaggerEditor@5 - 从下一个分支发布并部署在 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 Editor 允许您在浏览器中以 JSON 或 YAML 格式编辑OpenAPI API 定义（OpenAPI 2.0 和 OpenAPI 3.0.3），并实时预览文档。然后可以生成有效的 OpenAPI 定义并与完整的 Swagger 工具（代码生成、文档等）一起使用。

作为一个全新的版本，从头开始编写，存在一些已知问题和未实现的功能。查看“已知问题”部分了解更多详细信息。

该存储库发布到两个不同的 NPM 模块：

swagger-editor 是一个传统的 npm 模块，旨在用于能够解决依赖关系（通过 Webpack、Browserify 等）的单页应用程序。
swagger-editor-dist 是一个无依赖项模块，包含在服务器端项目或无法解析 npm 模块依赖项的 Web 项目中提供 Swagger 编辑器所需的一切。

如果您正在构建单页应用程序，强烈建议使用swagger-editor ，因为swagger-editor-dist明显更大。

匿名分析

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

 // package.json
{
  // ...
  "scarfSettings": {
    "enabled": false
  }
  // ...
}

或者，您可以将环境变量SCARF_ANALYTICS设置为false作为安装 npm 软件包的环境的一部分，例如SCARF_ANALYTICS=false npm install 。

有用的脚本

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

发展

脚本名称	描述
`dev`	在端口 3200 上生成热重载开发服务器。
`deps-check`	生成有关 Swagger Editors 依赖项的大小和许可报告。
`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.js 中运行基于 Mocha 的单元测试。
`test:unit-jest`	在 Node.js 中运行基于 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`导出为函数

本地运行

先决条件

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 Editor 进行代码更改，可以通过npm run dev启动 Webpack 热重载开发服务器。

浏览器支持

Swagger 编辑器适用于最新版本的 Chrome、Safari、Firefox 和 Edge。

已知问题

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

Swagger UI 的已知问题中列出的所有内容。
与 codegen 的集成仍然缺失。

码头工人

从 DockerHub 运行镜像

DockerHub 中发布了一个 docker 镜像。

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

 docker pull swaggerapi/swagger-editor
docker run -d -p 80:8080 swaggerapi/swagger-editor

这将在您计算机上的端口 80 上运行 Swagger Editor（以分离模式），因此您可以通过在浏览器中导航到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 跟踪代码管理器 ID，以跟踪 swagger-editor 的使用情况。

 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

重要的

在旧版本中，我们特指React >=17 <18 。

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

假设我的应用程序与swagger-editor@4 npm 包集成并使用 [email protected]。

新项目管理

为了通知swagger-editor@4 npm 包我需要它使用我的 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 重写被定义为对依赖项的引用。由于react-redux@9仅支持React >= 18 ，因此我们需要使用react-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 "
  }
}