在Linux上如何使用Swagger进行API文档共享

在 Linux 上使用 Swagger 进行 API 文档共享

一 方案总览

• 使用 Swagger Editor 在线编写与校验 OpenAPI 规范（YAML/JSON），使用 Swagger UI 将规范渲染成交互式文档页面，供团队浏览与调试。
• 文档共享的常见形态：
  • 本地或内网访问：直接通过 http://服务器IP:端口 打开页面。
  • 公网访问：配合 反向代理（Nginx） 或 内网穿透（如 Cpolar） 发布到公网域名或临时地址。
  • 与后端集成：在 Spring Boot 等项目中自动生成文档页面，随服务一起发布。

二 快速上手 原生部署 Swagger Editor 与 Swagger UI

• 安装 Node.js 与 npm（示例为 Ubuntu/Debian）：
  • 安装：sudo apt update && sudo apt install -y nodejs npm
  • 验证：node -v、npm -v
• 启动 Swagger Editor（静态文件服务方式）：
  • 安装静态服务器：npm install -g http-server
  • 启动：http-server -p 8080（浏览器访问：http://服务器IP:8080）
• 启动 Swagger UI（以 Express 托管 dist 为例）：
  • 准备目录与资源：将 Swagger UI 项目 dist 目录内容复制到 public/；创建 index.js：
    • const express = require(‘express’); const app = express(); app.use(‘/swagger’, express.static(‘public’)); app.listen(3000, () => console.log(‘http://localhost:3000/swagger’));
  • 启动：node index.js（浏览器访问：http://服务器IP:3000/swagger）
• 说明：Editor 用于编写/校验规范，UI 用于展示与调试，二者可分别部署在不同端口。

三 使用 Docker 部署 推荐

• 安装 Docker（示例）：
  • sudo apt-get update && sudo apt-get install -y docker.io
  • 启动与开机自启：sudo systemctl start docker && sudo systemctl enable docker
• 运行容器（将容器 8080 映射到宿主机端口，避免冲突）：
  • Swagger Editor：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  • Swagger UI：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
• 访问：
  • Editor：http://服务器IP:38080
  • UI：http://服务器IP:38081
• 提示：如需同时运行多个实例，请映射不同宿主机端口。

四 与 Spring Boot 集成 自动生成文档

• 使用 springdoc-openapi（推荐，基于 OpenAPI 3）：
  • 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，基于 Swagger 2）：
  • Maven 依赖：
    • io.springfox springfox-swagger2 2.9.2
    • io.springfox springfox-swagger-ui 2.9.2
  • 访问：http://服务器IP:8080/swagger-ui.html
• 说明：新项目优先使用 springdoc，与 Spring Boot 3 / Java 17+ 生态更契合。

五 安全与远程访问建议

• 反向代理与访问控制（以 Nginx 为例，仅示例思路）：
  • 配置基于 IP 或 Basic Auth 的访问控制；开启 HTTPS；将 /swagger 或 /swagger-ui 反向代理到实际服务。
• 内网穿透（无公网 IP 场景）：
  • 使用 Cpolar 等工具创建公网隧道，将本地 38080/38081 或容器端口映射为临时公网地址，便于外部分享与演示。
• 基础认证示例（概念）：
  • 在服务端增加 HTTP Basic Auth 中间件，对访问 /swagger 的请求进行用户名/密码校验后再转发，保护文档不被未授权访问。