ubuntu swagger部署流程是怎樣的

Ubuntu環境下Swagger的常見部署流程

一、前置準備

在部署Swagger前，需確保Ubuntu系統已安裝以下基礎工具：

• 更新系統包：sudo apt update && sudo apt upgrade -y
• 安裝curl（用于下載資源）：sudo apt install curl -y

二、方法一：使用Docker快速部署（推薦）

Docker是部署Swagger最便捷的方式，無需手動配置環境，保證環境一致性。

1. 安裝Docker

sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y

驗證Docker是否安裝成功：sudo docker run hello-world

2. 拉取Swagger UI Docker鏡像

docker pull swaggerapi/swagger-ui-express

（注：也可選擇其他官方鏡像，如openapi/swagger-ui）

3. 準備Swagger文檔

將你的swagger.yaml或swagger.json文件放置在項目根目錄（如/home/user/swagger-project/）。

4. 運行Swagger UI容器

docker run -d -p 8080:8080 -e SWAGGER_JSON=/app/swagger.yaml -v $(pwd):/app swaggerapi/swagger-ui-express

• -d：后臺運行容器；
• -p 8080:8080：將容器8080端口映射到主機8080端口；
• -e SWAGGER_JSON：指定Swagger文檔路徑（容器內為/app/swagger.yaml）；
• -v $(pwd):/app：將主機當前目錄掛載到容器/app目錄。

5. 訪問Swagger UI

打開瀏覽器，輸入http://localhost:8080，即可看到Swagger UI界面，展示swagger.yaml中的API文檔。

三、方法二：使用Node.js + Express集成部署

適用于已有Node.js項目的場景，將Swagger UI集成到現有應用中。

1. 安裝Node.js和npm

sudo apt install nodejs npm -y

驗證安裝：node -v、npm -v（建議使用nvm管理Node.js版本）。

2. 初始化Node.js項目

mkdir swagger-node-app && cd swagger-node-app
npm init -y

3. 安裝依賴

npm install express swagger-ui-express yamljs -S

• express：Web框架；
• swagger-ui-express：Swagger UI適配器；
• yamljs：解析YAML格式的Swagger文檔。

4. 創建Swagger文檔

在項目根目錄創建swagger.yaml，示例內容：

swagger: '2.0'
info:
  title: Sample API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string

5. 創建Express應用

創建server.js文件，內容如下：

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');

const app = express();
const swaggerDocument = YAML.load('./swagger.yaml'); // 加載Swagger文檔

// 集成Swagger UI到/api-docs路徑
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

// 示例API路由（可選）
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
});

6. 啟動應用

node server.js

7. 訪問Swagger UI

打開瀏覽器，輸入http://localhost:3000/api-docs，即可查看Swagger UI界面，同時可通過http://localhost:3000/users測試API。

四、方法三：手動部署Swagger Editor（用于編寫文檔）

若需要編寫或編輯Swagger文檔，可手動部署Swagger Editor。

1. 安裝Node.js和npm

（同方法二的步驟1、2）

2. 下載并啟動Swagger Editor

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install
npm install -g http-server
http-server -p 8080

3. 訪問Swagger Editor

打開瀏覽器，輸入http://localhost:8080，即可進入Swagger Editor界面，編寫或導入swagger.yaml/swagger.json文檔。

五、可選：配置Nginx反向代理（生產環境推薦）

若需通過域名訪問Swagger UI，或添加HTTPS支持，可配置Nginx反向代理。

1. 安裝Nginx

sudo apt install nginx -y

2. 配置Nginx

編輯默認站點配置文件：

sudo nano /etc/nginx/sites-available/default

替換為以下內容（以方法一的Docker部署為例）：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080; # 轉發到Swagger UI容器
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

3. 重啟Nginx

sudo systemctl restart nginx

（注：需將your-domain.com替換為你的實際域名，并配置DNS解析）

以上流程覆蓋了Ubuntu環境下Swagger的主要部署方式，可根據實際需求選擇。Docker方式適合快速部署，Node.js方式適合集成到現有項目，手動部署適合編寫文檔。