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的主要部署方式，可根据实际需求选择合适的方法。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！