centos swagger如何测试

在 CentOS 上测试 Swagger 的实用步骤

一 准备与本地验证

• 安装 Node.js 与 npm（示例为 Node.js 12.x）：
  • 安装编译依赖：sudo yum install -y gcc-c++ make
  • 配置 NodeSource 源并安装：curl -sL https://rpm.nodesource.com/setup_12.x | bash - 然后 sudo yum install -y nodejs
  • 验证：node -v、npm -v
• 启动 Swagger Editor（用于校验与编辑 OpenAPI/Swagger 文档）：
  • 准备目录并下载：mkdir -p /opt/swagger && cd /opt/swagger
  • 下载并解压 Editor（示例版本 v3.14.0）：wget https://github.com/swagger-api/swagger-editor/archive/v3.14.0.tar.gz && tar -xzf v3.14.0.tar.gz
  • 进入目录并起服务：cd swagger-editor-3.14.0 && npm install -g http-server && http-server -p 8081 &
  • 浏览器访问：http://<服务器IP>:8081，导入或编写 swagger.yaml/swagger.json 验证语法与结构是否正确。

二 在项目中展示 Swagger UI 并进行在线测试

• 方式 A（通用 Node.js + Express + Swagger UI 静态文件）
  • 下载 Swagger UI 静态文件（示例版本 v3.34.0）：cd /opt/swagger && wget https://github.com/swagger-api/swagger-ui/archive/v3.34.0.tar.gz && tar -xzf v3.34.0.tar.gz
  • 使用 Express 托管：cd swagger-ui-3.34.0 && npm init -y && npm install express --save
  • 复制静态资源：mkdir -p public && cp -r dist/* public/
  • 创建入口 index.js：

    const express = require('express');
    const app = express();
    app.use('/static', express.static('public'));
    app.get('/', (req, res) => res.send('Swagger UI is at /static/index.html'));
    app.listen(3000, () => console.log('Swagger UI listening on 3000'));
    

  • 启动服务：node index.js
  • 访问 http://<服务器IP>:3000/static/index.html，在页面 “URL” 处填入你的 swagger.json 地址（可为本地文件或远程地址），即可加载文档并进行在线调试。
• 方式 B（Java/Tomcat 项目）
  • 将应用部署到 Tomcat（默认端口 8080），访问：http://<服务器IP>:8080/<项目名>/swagger-ui.html 打开在线文档与调试界面。
• 方式 C（Go 项目，使用 go-swagger）
  • 生成文档：goctl api plugin -plugin goctl-swagger="swagger -filename bookstore.json -host <服务IP>:<端口> -basepath /" -api bookstore.api -dir .
  • 启动本地文档服务：./swagger_linux_amd64 serve -F=swagger bookstore.json --port 9088 --host 0.0.0.0 --no-open
  • 访问 http://<服务IP>:9088/docs 进行在线测试。

三 常见连通性与安全设置

• 放行访问端口（以 firewalld 为例）：
  • 开放端口：sudo firewall-cmd --add-port=8081/tcp --permanent（示例为 Swagger Editor 端口）
  • 重新加载：sudo firewall-cmd --reload
  • 其他端口（如 3000/9088/8080）按需开放。
• 解决 CORS 跨域（Swagger UI 与后端不在同域时常见）
  • 在后端添加响应头，例如：Access-Control-Allow-Origin: *（生产环境建议细化来源与凭据策略）。
• 生产环境建议
  • 为文档与接口启用 HTTPS 与 鉴权（如登录、Token/JWT），避免未授权访问与数据泄露。

四 快速排查清单

• 访问不到页面：检查服务是否运行、端口是否监听、防火墙是否放行、云服务器安全组是否允许入站。
• 文档空白或无法加载：确认 swagger.json 路径正确、可访问；必要时在 Swagger UI 的 “URL” 中填写可直接访问的在线地址。
• 调用接口失败：优先排查 CORS、接口路径与后端路由是否一致、请求头（如 Authorization）是否正确配置。