Linux下Swagger如何实现API文档共享

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

一 方案总览

• 使用 Swagger Editor 在线编写或粘贴 OpenAPI/Swagger 定义，使用 Swagger UI 渲染文档并通过链接共享给团队或外部合作方。
• 将文档与后端服务集成，直接在服务内提供 /swagger-ui 页面，适合内部系统联调。
• 微服务架构下通过 网关聚合（如 Spring Cloud Gateway + knife4j）提供统一文档入口，便于多服务统一查看与切换。
• 需要对外临时分享或远程协作时，结合 内网穿透（如 Cpolar）发布到公网，并可固定访问域名。

二 方案一 Docker快速部署Editor与UI

• 部署 Swagger Editor
  • 拉取并运行容器，将容器端口 8080 映射到宿主机 38080：

    docker pull swaggerapi/swagger-editor:v4.6.0
    docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
    

  • 访问地址：http://<服务器IP>:38080。
• 部署 Swagger UI
  • 拉取并运行容器，将容器端口 8080 映射到宿主机 38081：

    docker pull swaggerapi/swagger-ui:v4.15.5
    docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
    

  • UI 默认从 /swagger.json 加载文档。进入容器将示例 swagger.json 替换为你的定义，或在 UI 中通过 Import URL/File 指定你的 YAML/JSON：

    docker cp ./swagger.json <容器ID>:/usr/share/nginx/html/swagger.json
    

  • 访问地址：http://<服务器IP>:38081。

三 方案二 集成到Spring Boot并共享

• 使用 springdoc-openapi（推荐，适配 Spring Boot 3 / Spring Web MVC）
  • 添加依赖（Maven）：

    <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.1.0</version>
    </dependency>
    

  • 配置（application.properties）：

    springdoc.api-docs.path=/api-docs
    springdoc.swagger-ui.path=/swagger-ui
    

  • 启动后访问：http://<服务器IP>:8080/swagger-ui。
• 传统 springfox-swagger2（仅适用于较老版本 Spring Boot）
  • 依赖：

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
    </dependency>
    

  • 配置类启用 @EnableSwagger2 并构建 Docket 即可，访问 /swagger-ui.html。

四 方案三 微服务统一入口与远程共享

• 微服务聚合文档（网关 + knife4j）
  • 以 Spring Cloud Gateway + Nacos + knife4j 为例：在各微服务引入 knife4j 文档依赖并在网关聚合，实现单入口查看与切换多个服务的 API 文档，适合中大型微服务体系。
• 远程访问与固定公网地址
  • 在本机或服务器已运行文档服务（如 Editor 8088 端口）的前提下，使用 Cpolar 做内网穿透：
    • 一键安装与启动：

      curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash
      sudo systemctl enable --now cpolar
      

    • 浏览器访问 http://<局域网IP>:9200 登录 Cpolar Web UI，创建 HTTP 隧道：本地地址填 8088，协议 HTTP，地区自选；创建后获得公网 HTTP/HTTPS 地址，即可远程访问 Swagger Editor。
    • 需要长期稳定访问时，可在 Cpolar 中保留二级子域名并绑定到隧道，获得固定公网域名。

五 安全与运维建议

• 访问控制
  • 仅在内网开放文档端口，或通过反向代理（如 Nginx）加 Basic Auth / IP 白名单 / 反向代理鉴权；对外共享尽量使用临时链接或短期有效的公网地址。
• 版本与发布
  • 将 OpenAPI 定义纳入 Git 管理，UI 指向稳定分支或构建产物；变更通过 CI/CD 自动部署到文档站点。
• 网络与性能
  • 文档站点与后端服务分离部署，启用 GZIP 压缩与合适的 缓存 策略；必要时使用 CDN 加速静态资源。