如何在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 规范版本，避免频繁破坏性变更；变更时保留变更说明与兼容性策略。

0 赞

0 踩