Swagger在Linux环境如何部署

Swagger在Linux环境下的部署指南

Swagger（现更名为OpenAPI Specification）在Linux环境下的部署主要分为容器化部署（推荐）和传统手动部署两类，以下是具体步骤：

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

容器化部署无需关心依赖冲突，启动快速且易于管理，是最常用的部署方式。

1. 安装Docker

在Linux服务器上安装Docker，以Ubuntu为例：

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

2. 部署Swagger Editor（API文档编辑器）

拉取镜像：从Docker Hub获取Swagger Editor官方镜像（以v4.6.0版本为例）：
```
docker pull swaggerapi/swagger-editor:v4.6.0
```
运行容器：将容器的8080端口映射到宿主机的8088端口（可自定义）：
```
docker run -d -p 8088:8080 --name swagger-editor swaggerapi/swagger-editor:v4.6.0
```
访问Editor：在浏览器中输入http://服务器IP:8088，即可打开Swagger Editor界面，用于编写和编辑OpenAPI规范文件（YAML/JSON格式）。

3. 部署Swagger UI（API文档可视化工具）

拉取镜像：获取Swagger UI官方镜像（以v4.15.5版本为例）：
```
docker pull swaggerapi/swagger-ui:v4.15.5
```

运行容器：将容器的8080端口映射到宿主机的8080端口：

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

访问UI：在浏览器中输入http://服务器IP:8080，即可看到Swagger UI界面。默认会加载在线Petstore示例API，你也可以通过修改配置（如挂载本地swagger.json文件）展示自己的API文档。

4. （可选）配置远程访问

若需从外部网络访问，可使用Cpolar等工具将本地端口映射到公网：

安装Cpolar并登录，创建TCP隧道（如将宿主机8080端口映射到公网xxxx.cpolar.io:8080），获取公网地址后，即可通过该地址远程访问Swagger UI和Editor。

二、传统手动部署（适用于无Docker环境的Linux服务器）

若服务器未安装Docker，可通过手动安装Node.js、npm及Swagger相关组件实现部署。

1. 安装Node.js和npm

以Ubuntu为例，通过NodeSource仓库安装Node.js（推荐v16及以上版本）：

curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs

验证安装：

node -v  # 查看Node.js版本
npm -v   # 查看npm版本

2. 部署Swagger Editor

创建项目目录并初始化：

mkdir -p ~/swagger-editor
cd ~/swagger-editor
npm init -y

安装依赖：
```
npm install express http-server --save
```

创建启动脚本：在项目目录下创建index.js文件，内容如下：

const express = require('express');
const httpServer = require('http-server');
const path = require('path');

const app = express();
const server = httpServer.createServer(app);

// 静态文件服务（指向Swagger Editor的dist目录，需提前下载）
app.use(express.static(path.join(__dirname, 'swagger-editor-dist')));

const PORT = 8080;
server.listen(PORT, () => {
  console.log(`Swagger Editor running at http://localhost:${PORT}`);
});

下载Swagger Editor静态文件：从Swagger GitHub仓库下载swagger-editor-dist（如v3.50.0版本），解压后放入项目目录。
启动Editor：
```
node index.js
```
访问Editor：在浏览器中输入http://服务器IP:8080，即可使用Swagger Editor。

3. 部署Swagger UI

克隆仓库并安装依赖：

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui
npm install

构建项目：
```
npm run build
```

配置Web服务器（以Nginx为例）：

安装Nginx：
```
sudo apt install -y nginx
```

创建Nginx配置文件：在/etc/nginx/sites-available/下创建swagger-ui文件，内容如下：

server {
    listen 80;
    server_name 服务器IP或域名;
    root /path/to/swagger-ui/dist;  # 指向Swagger UI构建后的dist目录
    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界面，默认加载dist目录下的示例API，可通过修改swagger-initializer.js文件指向自己的swagger.json文件。

三、注意事项

端口开放：确保Linux服务器防火墙（如ufw或iptables）开放了对应端口（如8080、80），允许外部访问。
版本兼容：Swagger Editor和Swagger UI的版本需匹配（如均使用v4.x系列），避免因版本不兼容导致功能异常。
文档生成：若需自动生成API文档，可使用swagger-jsdoc（Node.js）或swagger-codegen（Java）等工具，根据代码注释生成swagger.json/swagger.yaml文件。

以上步骤覆盖了Linux环境下Swagger的主要部署方式，可根据实际需求选择合适的方法。