Ubuntu 上 Swagger 的 API 日志记录实践
一 核心原则与总体思路
- Swagger/OpenAPI 是规范与文档工具，本身不负责记录业务 API 的访问日志；日志应由承载 API 的后端框架或网关输出。常见做法是：在后端接入 HTTP 请求日志中间件（如 morgan、自定义中间件）、在 Swagger UI/Editor 中启用请求/响应拦截器输出调试信息，必要时将日志写入文件并由 logrotate 或 systemd journal 管理。若使用 Docker，则通过 docker logs 查看容器输出。
二 按运行形态的实施步骤
- 原生 Node.js + Express
- 安装日志中间件：npm i morgan；在 Express 中使用：app.use(morgan(‘combined’)) 输出 Apache 兼容格式；也可使用 ‘dev’/‘tiny’ 等格式。
- 若需在 Swagger UI 页面调试，给 swagger-ui-express 增加拦截器打印请求/响应：
- const swaggerUi = require(‘swagger-ui-express’);
const app = express();
app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
requestInterceptor: (req) => { console.log(‘Req:’, req); return req; },
responseInterceptor: (res) => { console.log(‘Res:’, res); return res; }
}));
- 运行后，API 访问日志将出现在应用控制台或被日志库写入文件；Swagger UI 自身的控制台日志可在浏览器开发者工具 Console 面板查看。
- Docker 部署
- 将应用日志输出到 stdout/stderr，通过 docker logs <container_id> 实时查看；如需持久化，挂载卷写入文件并在容器内使用 file 日志库。
- Systemd 服务
- 将后端或 Swagger Editor/UI 托管为服务（如 /etc/systemd/system/swagger-editor.service）；使用 journalctl 查看与跟踪：journalctl -u swagger-editor -f。
三 日志持久化与轮转
- 写入文件与权限
- 在 Node.js 中使用 winston/bunyan/pino 等日志库，配置日志文件路径（如 /var/log/myapi/access.log），并确保运行用户对目录有写权限（必要时使用 sudo 或调整所属用户/组）。
- logrotate 配置示例
- 新建 /etc/logrotate.d/myapi：
- /var/log/myapi/*.log {
- daily
- missingok
- rotate 7
- compress
- delaycompress
- notifempty
- create 0644 www-data www-data
- }
- 校验与强制执行：sudo logrotate -d /etc/logrotate.d/myapi（语法检查），sudo logrotate -f /etc/logrotate.d/myapi（强制轮转）。
- Systemd 日志维护
- 定期清理：sudo journalctl --vacuum-time=1w（保留最近一周），或 sudo journalctl --vacuum-size=500M（限制总大小）。
四 常见场景与排查要点
- 查看 Swagger UI/Editor 页面报错：打开浏览器开发者工具 Console 面板，定位前端资源加载或交互错误。
- 查看后端 API 访问日志：
- 原生进程：tail -f logs/access.log 或 journalctl -u -f；
- Docker：docker logs -f <container_id>；
- 若日志未输出，确认日志库已正确接入中间件/路由，且日志级别允许输出 INFO/DEBUG。
- 区分日志来源：Swagger UI/Editor 只提供文档与调试界面，真正的 API 访问日志来自后端应用或网关；如需集中化，可在网关层统一记录再下发到后端。
