如何在ubuntu上运行swagger文档

在 Ubuntu 上运行 Swagger 文档的实用方法

方法一 Docker 运行 Swagger UI（推荐）

• 安装 Docker（如未安装）：
  • sudo apt update
  • sudo apt install -y docker.io
• 直接运行容器并加载本地规范文件（JSON/YAML）：
  • docker run --rm -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v $(pwd):/app swaggerapi/swagger-ui-express
  • 将你的 swagger.yaml 或 swagger.json 放在当前目录，访问：http://localhost:8080
• 说明：该方式零依赖、隔离好，适合快速预览与分享文档。

方法二 Node.js + Express 集成 Swagger UI

• 安装 Node.js 与 npm：
  • sudo apt update
  • sudo apt install -y nodejs npm
• 初始化项目并安装依赖：
  • mkdir swagger-demo & & cd swagger-demo
  • npm init -y
  • npm install express swagger-ui-express yamljs
• 创建示例文件：
  • server.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} ));
  • swagger.yaml（最小可用示例）
    • openapi: 3.0.0 info: title: Sample API version: 1.0.0 paths: /ping: get: summary: 健康检查 responses: ‘200’: description: OK
• 启动服务：node server.js，访问：http://localhost:3000/api-docs。

方法三 同时运行 Swagger Editor 与 Swagger UI（编辑 + 预览）

• 安装 http-server（如未安装）：sudo npm install -g http-server
• 启动 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（浏览器访问：http://localhost:8080）
• 启动 Swagger UI（预览文档）：
  • wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
  • tar -xvf v3.48.0.tar.gz & & cd swagger-ui-3.48.0
  • npm install & & http-server -p 8081（浏览器访问：http://localhost:8081）
• 在 Editor 中编辑并保存 swagger.yaml/json，在 UI 中通过 URL 或粘贴内容加载并测试。

常见问题与排查

• 端口被占用：更换端口（如 8080→8082），或释放占用进程（lsof -i:8080 / kill ）。
• 容器无法读取本地文件：确认已用 -v $(pwd):/app 挂载当前目录，并使用 -e SWAGGER_JSON=/app/xxx.yaml 指定正确路径。
• 跨域问题（CORS）：若后端与 UI 不同源，需在后端开启 CORS 头（如 Access-Control-Allow-Origin）。
• 规范校验失败：使用 Editor 的 Validate 功能定位语法/结构错误；确保 openapi 版本与字段匹配（如 openapi: 3.0.0 对应 OAS3）。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！