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

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

一 方案总览

• 使用 Swagger Editor 在线或本地编写与评审 OpenAPI/Swagger 规范（YAML/JSON）。
• 使用 Swagger UI 将规范渲染成交互式文档页面，便于团队与第三方查看、调试。
• 通过 Docker 快速部署，或集成到 Node.js/Express 服务中托管文档。
• 将规范文件纳入 Git 版本控制，并配置 Nginx 反向代理与基础鉴权，实现安全共享与远程访问。

二 本地安装与快速启动

• 安装 Node.js 与 npm
  • 更新索引并安装：sudo apt update && sudo apt install -y nodejs npm
  • 验证版本：node -v、npm -v
• 启动 Swagger Editor
  • 下载并解压：wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.50.0.tar.gz && tar -xvf v3.50.0.tar.gz && cd swagger-editor-3.50.0
  • 安装静态服务器：npm install -g http-server
  • 启动服务：http-server -p 8080，访问：http://localhost:8080
• 启动 Swagger UI
  • 下载并解压：wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.50.0.tar.gz && tar -xvf v3.50.0.tar.gz && cd swagger-ui-3.50.0
  • 启动服务：http-server -p 8081，访问：http://localhost:8081
• 使用提示
  • Editor 默认加载示例规范，可通过导入本地 swagger.yaml/swagger.json 进行编辑与校验。
  • UI 页面可直接输入规范的 URL 加载并测试接口（Try it out）。

三 Docker 部署与远程访问

• 使用官方镜像运行 Swagger Editor
  • 拉取并启动：docker pull swaggerapi/swagger-editor && docker run -p 8088:8080 -d swaggerapi/swagger-editor
  • 访问：http://<服务器IP>:8088
• 使用 swaggerapi/swagger-ui-express 托管规范
  • 将当前目录挂载到容器并指定规范文件：docker run -p 8080:8080 -e SWAGGER_JSON=/app/swagger.json -v $(pwd):/app swaggerapi/swagger-ui-express
  • 访问：http://<服务器IP>:8080
• 远程协作与内网穿透（可选）
  • 结合内网穿透工具（如 Cpolar）为本地或内网环境生成公网可访问地址，便于外部协作与演示。

四 集成到现有服务与团队协作

• 在 Node.js/Express 中集成 Swagger UI
  • 安装依赖：npm install express swagger-ui-express yamljs
  • 示例代码（保存为 index.js）：

    const express = require('express');
    const swaggerUi = require('swagger-ui-express');
    const YAML = require('yamljs');
    const app = express();
    const swaggerDocument = YAML.load('./swagger.yaml'); // 或 swagger.json
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
    const PORT = process.env.PORT || 3000;
    app.listen(PORT, () => console.log(`Server running on ${PORT}`));
    

  • 访问：http://localhost:3000/api-docs
• 在 Spring Boot 项目中集成（可选）
  • 添加依赖（Maven）：

    <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>
    

  • 访问：http://localhost:8080/swagger-ui.html
• 团队协作与规范治理
  • 将 swagger.yaml/swagger.json 纳入 Git 仓库，配合 GitHub/GitLab 进行版本管理与评审。
  • 配置 CI/CD 在合并请求时自动校验规范合法性、预览文档站点，减少人工介入与漂移。

五 安全与运维建议

• 通过 Nginx 反向代理与基础鉴权共享文档
  • 示例 Nginx 配置片段：

    server {
      listen 80;
      server_name api-docs.example.com;
      location / {
        proxy_pass http://127.0.0.1:8080; # 指向 Swagger UI 或 Editor
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;
      }
    }
    

• 访问控制与网络边界
  • 仅在内网或受控网络开放文档端口，必要时结合 防火墙/安全组 限制来源 IP。
  • 为外部协作临时开启隧道或临时凭证，用后及时撤销。
• 规范与稳定性
  • 固定 OpenAPI/Swagger 规范版本，避免频繁破坏性变更；变更时保留变更说明与兼容性策略。