swaggerapi/swagger-editor

Swagger Editor Docker 镜像文档

镜像概述和主要用途

Swagger Editor 是一个基于浏览器的 OpenAPI API 定义编辑器，支持以 JSON 或 YAML 格式编辑 OpenAPI 规范（OpenAPI 2.0 和 OpenAPI 3.0.3），并实时预览文档。生成的有效 OpenAPI 定义可与完整的 Swagger 工具链（代码生成、文档等）配合使用。

该镜像提供了 Swagger Editor 的容器化部署方案，方便用户快速搭建和使用 Swagger Editor 服务。

版本说明： Swagger Editor 目前有两个主要发布渠道：

1. https://github.com/swagger-api/swagger-editor/releases?q=v4&expanded=true - 从 master 分支发布，部署于 [***]
2. https://github.com/swagger-api/swagger-editor/releases?q=v5&expanded=true - 从 next 分支发布，部署于 [***]

只有 SwaggerEditor@5 支持 https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md%E3%80%82SwaggerEditor@4 不支持 OpenAPI 3.1.0，现已被视为 legacy 版本。官方计划逐步迁移至 SwaggerEditor@5 并在未来弃用 SwaggerEditor@4。

核心功能和特性

• 支持 OpenAPI 2.0 和 OpenAPI 3.0.3 规范的编辑
• 实时语法检查和验证
• 实时文档预览
• 支持 JSON 和 YAML 格式
• 可导入外部 API 定义
• 代码生成功能（生成服务器和客户端代码）
• 可自定义各种端点和配置

浏览器支持：Swagger Editor 可在最新版本的 Chrome、Safari、Firefox 和 Edge 中运行。

使用场景和适用范围

• API 设计和开发人员编写、编辑和测试 OpenAPI 规范
• 团队协作中共享和评审 API 设计
• API 文档生成和预览
• 作为 API 开发工作流的一部分集成到 CI/CD 管道
• 教学和学习 OpenAPI 规范

使用方法和配置说明

从 DockerHub 运行镜像

Swagger Editor 镜像发布在 docker.swagger.io registry 上，可直接拉取和运行：

bash
# 拉取镜像
docker pull docker.swagger.io/swaggerapi/swagger-editor

# 基本运行
docker run -d -p 80:8080 docker.swagger.io/swaggerapi/swagger-editor

上述命令将在后台运行 Swagger Editor，映射到本地 80 端口。通过浏览器访问 http://localhost 即可使用。

高级配置选项

指定初始 API 定义文件

可通过 URL 提供指向 API 定义的链接：

bash
docker run -d -p 80:8080 -e URL="https://petstore3.swagger.io/api/v3/openapi.json" docker.swagger.io/swaggerapi/swagger-editor

或挂载本地 JSON/YAML 定义文件：

bash
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 将被忽略。

自定义基础 URL

如需在特定路径下访问应用（例如 http://localhost/swagger-editor/），可通过 BASE_URL 变量指定：

bash
docker run -d -p 80:8080 -e BASE_URL=/swagger-editor docker.swagger.io/swaggerapi/swagger-editor

自定义端口

默认容器内部端口为 8080，可通过 PORT 变量修改：

bash
docker run -d -p 80:80 -e PORT=80 docker.swagger.io/swaggerapi/swagger-editor

Google Tag Manager 集成

可通过 GTM 变量指定 Google Tag Manager ID 以跟踪使用情况：

bash
docker run -d -p 80:8080 -e GTM=GTM-XXXXXX docker.swagger.io/swaggerapi/swagger-editor

自定义端点配置

可通过以下环境变量自定义 Swagger Editor 使用的不同端点，这在拥有自己的 Swagger 生成器服务器时非常有用：

如果想在本地运行 Swagger Editor 而不使用 Codegen 功能（Generate Server 和 Generate Client），可将上述环境变量设置为 null：

bash
docker run -d -p 80:8080 -e URL_SWAGGER2_CONVERTER=null docker.swagger.io/swaggerapi/swagger-editor

docker-compose 配置示例

yaml
version: '3'
services:
  swagger-editor:
    image: docker.swagger.io/swaggerapi/swagger-editor
    container_name: swagger-editor
    restart: always
    ports:
      - "80:8080"
    environment:
      - BASE_URL=/swagger-editor
      - PORT=8080
      # - URL="https://petstore3.swagger.io/api/v3/openapi.json"
      # - GTM=GTM-XXXXXX
      # - URL_SWAGGER2_GENERATOR=null
      # - URL_OAS3_GENERATOR=null
      # - URL_SWAGGER2_CONVERTER=null
    volumes:
      # 可选：挂载本地文件
      # - ./swagger.json:/tmp/swagger.json
    networks:
      - swagger-network

networks:
  swagger-network:
    driver: bridge

本地构建和运行镜像

如果需要基于源码构建本地镜像，可执行以下步骤：

bash
# 克隆仓库（如果尚未克隆）
git clone https://github.com/swagger-api/swagger-editor.git
cd swagger-editor

# 安装 npm 依赖（如需）
npm install

# 构建应用
npm run build

# 构建 Docker 镜像
docker build -t swagger-editor .

# 运行容器
docker run -d -p 80:8080 swagger-editor

构建完成后，通过浏览器访问 http://localhost 即可使用。

文档和资源

• 导入 OpenAPI 文档
• https://github.com/swagger-api/.github/blob/HEAD/CONTRIBUTING.md

安全联系

如发现任何与安全相关的问题或漏洞，请发送电子邮件至 ***，而非使用公共 issue 跟踪器。