在Ubuntu上搭建Swagger API文档的详细步骤
1. 准备工作：安装Node.js和npm
Swagger UI是基于Node.js的工具，因此需要先安装Node.js和npm（Node.js包管理器）。
打开终端，执行以下命令更新包列表并安装：
sudo apt update
sudo apt install nodejs npm
安装完成后，验证版本以确保安装成功：
node -v # 查看Node.js版本
npm -v # 查看npm版本
（注：建议使用Node.js LTS版本，避免兼容性问题。）
2. 安装Swagger UI及相关依赖
Swagger UI的核心功能通过swagger-ui-express（Express中间件）和yamljs（解析YAML文件）实现，需通过npm全局安装：
sudo npm install -g swagger-ui-express yamljs
安装完成后，可通过swagger-ui-express -h验证是否安装成功。
3. 创建并配置Swagger文档
Swagger文档用于定义API的元数据（路径、参数、响应等），支持YAML或JSON格式。推荐使用YAML（更易读）。
在项目目录（如~/swagger-demo）下创建swagger.yaml文件，内容示例如下：
swagger: '2.0'
info:
title: Sample API
description: A demo API for Swagger UI integration
version: '1.0.0'
host: localhost:3000
basePath: /api
schemes:
- http
paths:
/users:
get:
summary: Get all users
description: Retrieve a list of all registered users
responses:
'200':
description: A JSON array of user objects
schema:
type: array
items:
$ref: '#/definitions/User'
definitions:
User:
type: object
properties:
id:
type: integer
format: int64
description: Unique user ID
name:
type: string
description: Full name of the user
email:
type: string
format: email
description: User's email address
（注：可根据实际API调整路径、参数和模型定义。）
4. 创建Express应用并集成Swagger UI
通过Express框架托管Swagger UI，步骤如下：
4.1 初始化项目
mkdir ~/swagger-demo && cd ~/swagger-demo
npm init -y # 创建package.json文件
4.2 安装Express和依赖
npm install express swagger-ui-express yamljs --save
4.3 创建入口文件index.js
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const YAML = require('yamljs');
// 加载Swagger文档
const swaggerDocument = YAML.load('./swagger.yaml');
const app = express();
// 托管Swagger UI，访问路径为/api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
// 示例API路由（可选，用于测试）
app.get('/api/users', (req, res) => {
res.json([
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
]);
});
// 启动服务器
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
console.log(`Swagger UI available at http://localhost:${PORT}/api-docs`);
});
4.4 启动应用
node index.js
启动后，终端会显示服务器地址和Swagger UI路径。
5. 访问Swagger UI
打开浏览器，访问http://localhost:3000/api-docs，即可看到Swagger UI界面。
- 左侧面板：显示API的路径、方法（如GET
/users）。 - 右侧面板：展示接口详情（摘要、描述、参数、响应示例）。
- 可直接在界面上测试接口（无需额外工具）。
6. 可选：使用Docker部署（简化环境配置）
若不想手动配置Node.js环境，可使用Docker快速部署：
6.1 安装Docker
sudo apt update
sudo apt install docker.io
sudo systemctl start docker
sudo systemctl enable docker
6.2 创建Dockerfile
在项目根目录（~/swagger-demo）下创建Dockerfile，内容如下：
FROM node:18-alpine # 使用轻量级Alpine版Node.js
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]
6.3 构建并运行Docker容器
docker build -t swagger-demo .
docker run -d -p 3000:3000 --name swagger-container swagger-demo
访问http://localhost:3000/api-docs即可查看Swagger UI。
注意事项
- 权限问题：若安装或运行时出现权限错误，可在命令前加
sudo（如sudo npm install -g swagger-ui-express）。 - 端口修改：若默认端口（3000）被占用，可在
index.js中修改PORT变量（如const PORT = 8080），并同步修改访问地址。 - 文档自动化：可通过
swag init命令（需安装swag工具）从代码注释自动生成Swagger文档，减少手动维护成本。
以上就是关于“Ubuntu如何搭建Swagger API文档”的相关介绍，筋斗云是国内较早的云主机应用的服务商，拥有10余年行业经验，提供丰富的云服务器、租用服务器等相关产品服务。云服务器资源弹性伸缩，主机vCPU、内存性能强悍、超高I/O速度、故障秒级恢复；电子化备案，提交快速，专业团队7×24小时服务支持！
简单好用、高性价比云服务器租用链接：https://www.jindouyun.cn/product/cvm