Ubuntu 环境下 Swagger 常见报错与处理清单
一、先定位问题
ss -tulpen | grep -E '3000|5000|8080'curl -I http://127.0.0.1:8080/swagger-ui/curl -I http://服务器IP:8080/swagger-ui/二、常见报错与对应处理
http-server)验证资源是否可达。三、按技术栈的排查与修复步骤
springdoc.swagger-ui.path 或 swagger-ui 前缀与反向代理一致。try_files 与 proxy_pass 不会拦截 /swagger-ui/** 与 /v3/api-docs/**。Program.cs 正确注册:AddSwaggerGen / UseSwagger / UseSwaggerUI,设置正确的 SwaggerEndpoint(如 /swagger/v1/swagger.json)。SwaggerGenerator 的详细异常堆栈以定位配置或依赖问题。sudo apt update && sudo apt install -y nodejs npm;全局安装 http-server 或使用 swagger-ui-express 托管 UI。nohup http-server . -p 8080 &),避免仅用 Ctrl+Z 挂起导致端口占用与后续 404/端口漂移。四、Nginx 与防火墙的快速修复示例
server {
listen 80;
server_name your.domain.com;
location /swagger-ui/ {
proxy_pass http://127.0.0.1:8080/swagger-ui/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /v3/api-docs/ {
proxy_pass http://127.0.0.1:8080/v3/api-docs/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
sudo ufw allow 8080/tcpsudo firewall-cmd --add-port=8080/tcp --permanent && sudo firewall-cmd --reload