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界面。

三、注意事项

端口开放：确保Linux防火墙（如ufw）开放了对应端口（如80、8080、8081）：
```
sudo ufw allow 80/tcp
sudo ufw allow 8080/tcp
sudo ufw allow 8081/tcp
```
持久化数据：若使用Docker部署，可通过-v参数挂载数据卷，避免容器重启后数据丢失（如Swagger Editor的配置文件）。
版本兼容：确保Swagger Editor和UI的版本兼容（如均使用v4.x系列），避免功能异常。

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

0 赞

0 踩