Linux环境中Swagger如何实现API文档的共享

Linux环境下Swagger共享API文档的实用方案

一 方案总览

• 使用 Swagger Editor 在线编写或校验 OpenAPI/Swagger 定义，使用 Swagger UI 渲染文档页面，供团队浏览与调试。
• 将文档托管在 Linux 服务器上，通过 Nginx/Apache 反向代理与简单鉴权对外共享。
• 在 Spring Boot 项目中集成文档生成（推荐 springdoc-openapi，也可选 springfox），直接以服务内置页面共享。
• 需要外网访问时，结合 Docker 快速部署，或使用 内网穿透 工具发布到公网。

二 原生部署与共享步骤

• 安装运行环境
  • 安装 Node.js/npm：
    • Ubuntu/Debian 示例：
      • curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
      • sudo apt-get install -y nodejs
      • node -v && npm -v
• 部署 Swagger Editor
  • 下载并启动：
    • wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.50.0.tar.gz
    • tar -xvf swagger-editor-3.50.0.tar.gz && cd swagger-editor-3.50.0
    • npm install -g http-server
    • http-server -p 8080
  • 访问：http://<服务器IP>:8080
• 部署 Swagger UI
  • 下载并启动：
    • wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.50.0.tar.gz
    • tar -xvf swagger-ui-3.50.0.tar.gz && cd swagger-ui-3.50.0
    • npm install -g http-server
    • http-server -p 8081
  • 访问：http://<服务器IP>:8081（将页面中的 URL 指向你的 OpenAPI JSON/YAML 即可）
• 共享要点
  • 将 YAML/JSON 定义文件放到可被 HTTP 访问的位置（与 UI 同域或配置可跨域），在 UI 中设置 “URL” 加载定义。
  • 通过 Nginx 反向代理统一域名与端口，便于权限控制与 HTTPS 配置。

三 Docker快速部署与远程访问

• 使用官方镜像运行
  • Swagger Editor：
    • docker pull swaggerapi/swagger-editor:v4.6.0
    • docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  • Swagger UI：
    • docker pull swaggerapi/swagger-ui:v4.15.5
    • docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
  • 访问：
    • Editor：http://<服务器IP>:38080
    • UI：http://<服务器IP>:38081
• 远程访问与内网穿透（可选）
  • 无公网 IP 时，可用 Cpolar 等工具做内网穿透，将本地 38080/38081 暴露为公网可访问地址，再把公网地址分发给协作方。

四 在Spring Boot中集成与共享

• 使用 springdoc（推荐，适配 Spring Boot 3 / Spring Web MVC / WebFlux）
  • 依赖（Maven）：
    • - org.springdoc - springdoc-openapi-starter-webmvc-ui - 2.1.0 -
  • 配置（application.properties）：
    • springdoc.api-docs.path=/api-docs
    • springdoc.swagger-ui.path=/swagger-ui
  • 访问：http://<服务器IP>:8080/swagger-ui
• 使用 springfox（旧项目兼容）
  • 依赖（Maven）：
    • - io.springfox - springfox-swagger2 - 2.9.2 -
    • - io.springfox - springfox-swagger-ui - 2.9.2 -
  • 配置类启用 Swagger2 后，访问：http://<服务器IP>:8080/swagger-ui.html

五 安全与协作建议

• 访问控制
  • 在内网环境通过 反向代理（Nginx） 配置 Basic Auth 或 IP 白名单；对外发布时优先使用 HTTPS。
• 文档来源与一致性
  • 将 OpenAPI 文件纳入 Git 管理，Editor 与 UI 均从仓库或内网静态站点加载，避免散落在个人环境。
• 外网临时共享
  • 无公网 IP 时，使用 Cpolar 等内网穿透工具发布 Editor/UI 的临时公网地址，设置强口令与有效期，用完即停。