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方式适合集成到现有项目，手动部署适合编写文档。