温馨提示×

debian swagger怎么分享

小樊
48
2026-10-25 06:35:28
栏目: 智能运维

在 Debian 上“分享 Swagger”一般有几种常见场景,下面按最常见用法给你说明,你可以看看哪种符合你的情况。


一、Swagger UI 本地已运行,想让别人访问

1️⃣ 确认 Swagger UI 监听地址

很多框架默认只监听 127.0.0.1,外网/局域网访问不了。

例如(Spring Boot):

springdoc:
  swagger-ui:
    enabled: true

确保服务监听:

ss -lntp | grep 8080

如果是:

127.0.0.1:8080

别人是访问不到的。

2️⃣ 改为监听 0.0.0.0(示例)

server:
  address: 0.0.0.0
  port: 8080

或 Nginx / 代码中显式绑定 0.0.0.0


二、通过 Nginx 反向代理分享(推荐)

安装 Nginx

sudo apt update
sudo apt install nginx

配置示例

server {
    listen 80;
    server_name swagger.example.com;

    location /swagger-ui/ {
        proxy_pass http://127.0.0.1:8080/swagger-ui/;
    }

    location /v3/api-docs/ {
        proxy_pass http://127.0.0.1:8080/v3/api-docs/;
    }
}

重载:

sudo nginx -t
sudo systemctl reload nginx

别人访问:

http://服务器IP/swagger-ui.html

三、直接分享 Swagger JSON / YAML(最简单)

导出 API 文档

常见地址:

  • OpenAPI 3:/v3/api-docs
  • Swagger 2:/v2/api-docs
curl http://localhost:8080/v3/api-docs > openapi.json

分享方式

  • 发文件给同事
  • 上传到内网网盘
  • 用 GitHub / GitLab
  • 用静态服务器:
python3 -m http.server 8000

访问:

http://服务器IP:8000/openapi.json

四、生成静态 Swagger 页面(可公网/内网访问)

使用 swagger-ui 静态版

git clone https://github.com/swagger-api/swagger-ui.git
cp openapi.json swagger-ui/dist/

修改:

url: "openapi.json"

部署:

sudo cp -r swagger-ui/dist /var/www/html/swagger

访问:

http://服务器IP/swagger

五、安全提醒(很重要)

  • ❌ 不要直接把 Swagger 暴露公网
  • ✅ 加账号密码 / IP 白名单
  • ✅ 生产环境关闭 Swagger

Nginx 简单鉴权:

location /swagger-ui/ {
    auth_basic "Swagger";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

你可以告诉我:

  1. 用的是什么?(Spring Boot / Node / FastAPI / 其他)
  2. 想局域网分享还是公网
  3. 已有 Swagger UI 还是只有 JSON

我可以直接给你对应配置文件。

0 踩