如何在Ubuntu上用Swagger进行API监控 - 问答

在Ubuntu上用Swagger进行API监控的步骤

1. 安装前置工具（Node.js与npm）

Swagger Editor和Swagger UI均需通过npm（Node.js包管理器）安装，因此需先确保系统具备Node.js环境。
打开终端，执行以下命令更新包列表并安装Node.js及npm：

sudo apt update
sudo apt install nodejs npm

安装完成后，可通过node -v和npm -v验证安装是否成功。

2. 安装Swagger Editor与Swagger UI

方法一：使用npm全局安装（推荐）

通过npm直接安装Swagger Editor和Swagger UI（简化部署流程）：

npm install -g swagger-editor
npm install -g swagger-ui-express

方法二：手动下载并启动

若需自定义配置，可下载Swagger的压缩包并手动启动：

Swagger Editor：下载v3.16.1版本，解压后进入目录，执行npm install -g http-server启动静态服务器：

wget https://github.com/swagger-api/swagger-editor/archive/refs/tags/v3.16.1.tar.gz
tar -xvf v3.16.1.tar.gz
cd swagger-editor-3.16.1
npm install -g http-server
http-server -p 8080

Swagger UI：下载v3.48.0版本，解压后进入目录，安装依赖并启动Express服务：

wget https://github.com/swagger-api/swagger-ui/archive/refs/tags/v3.48.0.tar.gz
tar -xvf v3.48.0.tar.gz
cd swagger-ui-3.48.0
npm install -g express
node index.js

安装完成后，Swagger Editor可通过http://localhost:8080访问，Swagger UI通过http://localhost:3000访问。

3. 配置Swagger文档

Swagger Editor配置

启动Swagger Editor后，点击页面左侧的“+”号或“Import File”按钮，上传本地的swagger.yaml（或swagger.json）文件。编辑完成后，可实时预览API文档的结构和内容。

Swagger UI配置

启动Swagger UI后，在浏览器页面的输入框中粘贴Swagger文档的URL（如http://localhost:8080/swagger.yaml），或点击“Choose File”上传本地文件，点击“Explore”按钮即可加载并查看API文档。

4. 基础API测试（Swagger UI自带功能）

Swagger UI提供了“Try it out”按钮，可直接在界面上测试API的请求与响应：

选择需要测试的API端点（如GET /users）；
点击“Try it out”，系统会自动生成请求示例；
输入必要的参数（如查询条件、请求体），再次点击“Execute”即可发送请求；
页面会显示服务器返回的响应状态码、响应时间和响应体，便于快速验证API功能。

5. 高级监控：集成Prometheus+Grafana（可选但推荐）

若需监控API的使用频率、响应时间、错误率等指标，需借助Prometheus（数据采集）和Grafana（可视化）工具：

① 暴露OpenAPI规范

确保Swagger生成的swagger.yaml或swagger.json文件可通过网络访问（如将文件放在Web服务器根目录，或通过Express路由暴露）：

// 示例：Express暴露swagger.yaml
const express = require('express');
const YAML = require('yamljs');
const app = express();

const swaggerDocument = YAML.load('./swagger.yaml');
app.get('/swagger.json', (req, res) => {
  res.json(swaggerDocument);
});

app.listen(8080, () => console.log('Swagger docs exposed at http://localhost:8080/swagger.json'));

② 安装并配置Prometheus

下载Prometheus（如v2.30.3），编辑prometheus.yml文件，添加Swagger文档的抓取目标：

wget https://github.com/prometheus/prometheus/releases/download/v2.30.3/prometheus-2.30.3.linux-amd64.tar.gz
tar xvfz prometheus-2.30.3.linux-amd64.tar.gz
cd prometheus-2.30.3.linux-amd64

修改prometheus.yml，添加以下内容：

scrape_configs:
  - job_name: 'swagger'
    static_configs:
      - targets: ['localhost:8080']  # Swagger文档所在地址

启动Prometheus：

./prometheus --config.file=prometheus.yml

③ 安装并配置Grafana

下载Grafana（如v8.2.0），启动服务并设置数据源为Prometheus：

wget https://dl.grafana.com/oss/release/grafana-8.2.0.linux-amd64.tar.gz
tar -zxvf grafana-8.2.0.linux-amd64.tar.gz
cd grafana-8.2.0

编辑conf/grafana.ini，配置Prometheus数据源：

[data]
type = Prometheus
url = http://localhost:9090

启动Grafana：

./bin/grafana-server web

访问http://localhost:3000（默认账号admin/admin），添加Prometheus数据源后，可导入Swagger监控仪表板模板（如社区提供的“Swagger API Metrics”模板），实现API使用情况的可视化监控。

注意事项

确保防火墙允许Swagger Editor（默认8080端口）、Swagger UI（默认3000端口）、Prometheus（默认9090端口）和Grafana（默认3000端口）的访问；
若需长期监控，建议将Prometheus和Grafana配置为系统服务（通过systemctl管理），确保开机自启；
Swagger本身仅提供文档功能，监控指标需通过集成第三方工具实现。

0 赞

0 踩