Ubuntu上使用 Swagger UI 的简明指南
一 准备环境
- 更新系统并安装基础工具：
- sudo apt update
- sudo apt install -y curl wget
- 如需在本地开发集成，建议安装 Node.js 与 npm（可选）：
- sudo apt install -y nodejs npm
- 验证：node -v 与 npm -v 能正常输出版本号。
二 三种常用方式
- 方式一 Docker 运行 Swagger UI（最快速）
- 拉取并运行容器（内置示例页，便于验证环境）：
- docker run -p 8080:8080 swaggerapi/swagger-ui-express
- 浏览器访问：http://localhost:8080（如需加载自有规范，见下方“加载自定义规范”）。
- 方式二 Node.js + Express 集成（适合把文档与后端服务一起托管）
- 初始化项目并安装依赖：
- mkdir swagger-demo && cd swagger-demo
- npm init -y
- npm install express swagger-ui-express yamljs
- 创建示例文件：
- 新建 swagger.yaml（示例见下节）
- 新建 app.js：
- const express = require(‘express’);
const swaggerUi = require(‘swagger-ui-express’);
const YAML = require(‘yamljs’);
const swaggerDocument = YAML.load(‘./swagger.yaml’);
const app = express();
app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(
Server running on ${PORT}));
- 启动与访问：
- node app.js
- 浏览器访问：http://localhost:3000/api-docs
- 方式三 直接使用官方静态文件托管（静态站点思路）
- 下载并解压 Swagger UI 源码，将其中的 dist 目录作为静态文件目录，用任意静态服务器托管（如 Nginx/Apache 或 http-server）。
- 访问托管后的页面，在页面中指定你的 swagger.json / swagger.yaml 的 URL 进行加载。
三 加载自定义规范与在线编辑
- 加载本地或远程规范文件
- Docker 启动时挂载规范并指定 URL 路径（容器内 /spec 目录放你的文件）：
- docker run -p 8080:8080 -v $(pwd)/spec:/spec swaggerapi/swagger-ui-express
- 访问：http://localhost:8080?url=/spec/swagger.yaml（或 /spec/swagger.json）
- Express 集成时直接把解析后的对象传入 setup：
- app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
- 使用 Swagger Editor 在线编写与导出
- 快速启动编辑器（容器方式）：
- docker pull swaggerapi/swagger-editor
- docker run -p 8081:8080 swaggerapi/swagger-editor
- 浏览器访问：http://localhost:8081，编辑后导出 YAML/JSON 再用于 UI 加载。
四 示例 swagger.yaml 与常见问题
- 示例 swagger.yaml（OpenAPI 3.0）
- openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
servers:
- url: http://localhost:3000
description: 开发服务器
paths:
/users:
get:
summary: 获取用户列表
responses:
‘200’:
description: 用户列表
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
- 常见问题与处理
- 端口被占用：更换 -p 参数（如 8080→8082），或释放占用端口后再启动。
- CORS 跨域：若 UI 与后端不在同域，需在后端开启 CORS（如 Access-Control-Allow-Origin 等）。
- 容器无法访问主机服务：在 Docker 中访问宿主机使用 host.docker.internal（Linux 上某些环境可用），或改用宿主机 IP。
- 规范校验失败：使用 Swagger Editor 校验 YAML/JSON 语法与结构，再导入 UI。
