Swagger工具在Linux上如何部署与运行

Swagger工具在Linux上的部署与运行指南

Swagger是一款流行的API文档生成与管理工具，在Linux环境下的部署主要分为Docker容器化部署（推荐，便捷高效）和传统手动部署（适合需要自定义配置的场景）两类。以下是详细步骤：

一、Docker容器化部署（推荐）

Docker容器化部署无需手动配置运行环境，隔离性好，适合快速部署和迁移。

1. 安装Docker

首先确保Linux系统已安装Docker。若未安装，可通过以下命令完成（以Ubuntu/Debian为例）：

sudo apt update
sudo apt install -y docker.io
sudo systemctl start docker  # 启动Docker服务
sudo systemctl enable docker # 设置开机自启

安装完成后，通过docker --version验证是否安装成功。

2. 部署Swagger Editor

Swagger Editor用于在线编写和测试OpenAPI规范（YAML/JSON格式）。

• 拉取镜像：选择最新稳定版本的Swagger Editor镜像（如v4.6.0）：

  docker pull swaggerapi/swagger-editor:v4.6.0
  

• 运行容器：将容器的8080端口映射到宿主机的8080端口（可根据需求调整）：

  docker run -d -p 8080:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0
  

• 访问Editor：在浏览器中输入http://<服务器IP>:8080，即可进入Swagger Editor界面。

3. 部署Swagger UI

Swagger UI用于可视化展示和测试API文档。

• 拉取镜像：选择与Editor兼容的Swagger UI镜像（如v4.15.5）：

  docker pull swaggerapi/swagger-ui:v4.15.5
  

• 运行容器：将容器的8080端口映射到宿主机的8081端口（避免与Editor端口冲突）：

  docker run -d -p 8081:8080 --name swagger-ui swaggerapi/swagger-ui:v4.15.5
  

• 访问UI：在浏览器中输入http://<服务器IP>:8081，即可进入Swagger UI界面。

二、传统手动部署

若需自定义Swagger配置或无法使用Docker，可选择手动部署。

1. 安装Node.js和npm

Swagger Editor和UI的Node.js版本需要Node.js运行环境。通过以下命令安装：

sudo apt update
sudo apt install -y nodejs npm

安装完成后，通过node -v和npm -v验证安装。

2. 部署Swagger Editor

• 下载并解压：从Swagger GitHub仓库下载指定版本的Swagger Editor（如v3.50.0）：

  mkdir -p /opt/swagger-editor
  cd /opt/swagger-editor
  wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.50.0.tar.gz
  tar -xvf v3.50.0.tar.gz
  rm v3.50.0.tar.gz
  

• 安装依赖：进入解压目录，安装Express等依赖：

  cd swagger-editor-3.50.0
  npm install express --save
  

• 配置并启动：创建index.js文件，内容如下：

  const express = require('express');
  const app = express();
  app.use('/swagger', express.static('public')); // 静态文件目录
  app.get('/', (req, res) => res.send('Swagger Editor已启动'));
  const PORT = 3000;
  app.listen(PORT, () => console.log(`访问地址：http://<服务器IP>:${PORT}`));
  

• 启动服务：运行node index.js，通过http://<服务器IP>:3000/swagger访问Editor。

3. 部署Swagger UI

• 下载并解压：从Swagger GitHub仓库下载指定版本的Swagger UI（如v3.48.0）：

  mkdir -p /opt/swagger-ui
  cd /opt/swagger-ui
  wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
  tar -xvf v3.48.0.tar.gz
  rm v3.48.0.tar.gz
  

• 配置Web服务器：以Nginx为例，创建服务器块配置文件：

  sudo nano /etc/nginx/sites-available/swagger-ui
  

  添加以下内容（将/var/www/html替换为Swagger UI解压后的目录路径）：

  server {
      listen 80;
      server_name <服务器IP或域名>;
      root /opt/swagger-ui/swagger-ui-3.48.0/dist; # Swagger UI静态文件目录
      index index.html;
      location / {
          try_files $uri $uri/ /index.html; # 支持前端路由
      }
  }
  

• 启用配置并重启Nginx：

  sudo ln -s /etc/nginx/sites-available/swagger-ui /etc/nginx/sites-enabled/
  sudo nginx -t  # 测试配置语法
  sudo systemctl restart nginx
  

• 访问UI：在浏览器中输入http://<服务器IP>，即可看到Swagger UI界面。

三、注意事项

1. 端口开放：确保Linux防火墙（如ufw）开放了对应端口（如80、8080、8081）：

   sudo ufw allow 80/tcp
   sudo ufw allow 8080/tcp
   sudo ufw allow 8081/tcp
   

2. 持久化数据：若使用Docker部署，可通过-v参数挂载数据卷，避免容器重启后数据丢失（如Swagger Editor的配置文件）。
3. 版本兼容：确保Swagger Editor和UI的版本兼容（如均使用v4.x系列），避免功能异常。

通过以上步骤，即可在Linux系统上成功部署并运行Swagger工具，实现API文档的编写、展示与测试。