Ubuntu Swagger怎样集成到项目中

在 Ubuntu 上集成 Swagger OpenAPI 的实用步骤

一 前置准备

• Ubuntu 环境准备：更新软件源并安装 Node.js 与 npm（用于 Node 系集成），或安装 Docker（用于容器化集成）。
  • Node.js 与 npm
    • 命令：sudo apt update && sudo apt install -y nodejs npm
  • Docker
    • 命令：sudo apt update && sudo apt install -y docker.io
• 概念说明：日常所说的 Swagger 现已统一为 OpenAPI 规范，工具链包含 Swagger Editor（编辑规范）、Swagger UI（可视化文档与调试）。

二 Node.js Express 项目集成

• 安装依赖
  • 全局：sudo npm install -g swagger-jsdoc swagger-ui-express
  • 项目内：npm install swagger-ui-express
• 准备 API 规范
  • 方式 A：手写 swagger.json / swagger.yaml
  • 方式 B：用 swagger-jsdoc 从代码注释生成（需按 JSDoc 规范书写注释）
• 在 Express 中挂载 Swagger UI
  • 示例代码（CommonJS）：
    • const express = require(‘express’);
    • const swaggerUi = require(‘swagger-ui-express’);
    • const swaggerDocument = require(‘./swagger.json’); // 或 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 ${port}));
• 访问文档
  • 浏览器打开：http://localhost:3000/api-docs
• 生成客户端代码（可选）
  • 命令：npx swagger-jsdoc -o ./generated -d ./path/to/swagger/swagger.json
• 提示
  • 若使用 YAML，可安装 yamljs 并在代码中用 YAML.load(‘./swagger.yaml’) 加载。

三 使用 Docker 快速托管 Swagger UI

• 拉取镜像：docker pull swaggerapi/swagger-ui-express
• 运行容器（将本地规范挂载到容器内并指定展示路径）
  • 命令示例：docker run -p 8080:8080 -e SWAGGER_JSON=/spec/swagger.json -v $(pwd)/swagger.json:/spec/swagger.json swaggerapi/swagger-ui-express
• 访问文档
  • 浏览器打开：http://localhost:8080
• 说明
  • 通过环境变量 SWAGGER_JSON 指定规范文件路径；也可挂载 swagger.yaml 并在环境变量中指向对应路径。

四 Spring Boot 项目集成简述

• Springfox 2.x（较老）
  • 依赖（Maven）：
    • io.springfox:springfox-swagger2:2.9.2
    • io.springfox:springfox-swagger-ui:2.9.2
  • 配置类启用 @EnableSwagger2，访问路径通常为：http://localhost:8080/swagger-ui.html
• Springfox 3.x（OpenAPI 3）
  • 依赖（Maven）：org.springfox:springfox-boot-starter:3.0.0
  • 访问路径通常为：http://localhost:8080/swagger-ui/index.html
• 提示
  • Springfox 已进入维护模式，生产可考虑 SpringDoc OpenAPI（springdoc-openapi）替代，整合更简洁。

五 常见问题与排查

• 访问不到页面
  • 确认服务已启动且端口已放行（如 3000、8080）；如使用反向代理或容器，核对路由与端口映射。
• 规范加载失败
  • 核对 swagger.json / swagger.yaml 路径、语法与引用；YAML 需使用相应解析库加载。
• 容器中文或静态资源异常
  • 挂载规范文件时确保读写权限与编码一致；必要时设置容器内环境变量与工作目录。
• 规范与代码不一致
  • 使用 swagger-jsdoc 时，确保注释符合规范并覆盖最新接口；变更后重新生成或重启服务。