如何在Ubuntu上使用Swagger UI

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.0info:title: Sample APIversion: 1.0.0servers:
    • url: http://localhost:3000description: 开发服务器paths:/users:get:summary: 获取用户列表responses:‘200’:description: 用户列表content:application/json:schema:type: arrayitems:type: objectproperties:id:type: integername:type: string
• 常见问题与处理
  • 端口被占用：更换 -p 参数（如 8080→8082），或释放占用端口后再启动。
  • CORS 跨域：若 UI 与后端不在同域，需在后端开启 CORS（如 Access-Control-Allow-Origin 等）。
  • 容器无法访问主机服务：在 Docker 中访问宿主机使用 host.docker.internal（Linux 上某些环境可用），或改用宿主机 IP。
  • 规范校验失败：使用 Swagger Editor 校验 YAML/JSON 语法与结构，再导入 UI。