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