在 CentOS 上调用 Swagger API 的实用步骤
一 准备与访问 Swagger UI
- 使用 Docker 快速启动 Swagger Editor 与 Swagger UI（推荐，隔离环境、部署快）：
- 启动 Editor：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
- 启动 UI：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
- 访问地址：Editor 为 http://<服务器IP>:38080，UI 为 http://<服务器IP>:38081。在 UI 的页面中，将 URL 指向你的 swagger.json/swagger.yaml 即可加载文档。若文档在本地或内网，需保证 UI 容器能访问到该地址。
- 非 Docker 方式（Node.js/npm）：
- 安装工具：npm install -g swagger-ui-express swagger-jsdoc
- 在 Express 中集成：
- const swaggerUi = require(‘swagger-ui-express’); const swaggerDocument = require(‘./swagger.json’);
- app.use(‘/api-docs’, swaggerUi.serve, swaggerUi.setup(swaggerDocument));
- 启动服务后访问 http://<服务器IP>:3000/api-docs。如使用源码包部署 UI，需将 dist 内容托管到静态目录并在页面中修改指向你的 JSON/YAML 的 URL。
二 在 Swagger UI 中调用接口
- 打开 Swagger UI，选择目标 API 路径 与 HTTP 方法（如 GET/POST/PUT/DELETE）。
- 点击 Try it out，填写 query/path/header/formData/body 等参数。
- 点击 Execute 发送请求，查看 状态码、响应体、响应头 与 耗时。
- 常见要点：
- 注意 Content-Type（如 application/json、application/x-www-form-urlencoded、multipart/form-data）与参数位置需与方法定义一致。
- 需要鉴权时，先在 UI 的 Authorize 区域填入 Bearer Token 或 API Key，再执行请求。
三 在终端用 curl 复现调用
- GET 查询参数：curl “http://172.16.110.147:9090/client/selectByPage?limit=10&page=1”
- POST 表单：curl -X POST http://172.16.110.147:9090/factory/insert
-H “Content-Type: application/x-www-form-urlencoded”
-d “factoryName=TestFactory&no=123&remark=TestRemark”
- POST JSON：curl -X POST http://172.16.110.147:9090/material/selectAll
-H “Content-Type: application/json”
-d ‘{“factory”:“TestFactory”,“materialName”:“TestMaterial”,“materialNo”:“12345”,“offset”:0,“page”:1,“pageSize”:10}’
- 上传文件 multipart/form-data：curl -X POST http://172.16.110.147:9090/api/all/order/money
-F “file=@/path/to/file” -F “startTime=2020-01-01” -F “endTime=2020-06-30”
- 如需携带鉴权：在 Header 中添加 Authorization: Bearer 或 X-API-Key: 。
四 常见问题与排查
- CORS 跨域：在后端服务添加响应头，例如 **Access-Control-Allow-Origin: ***（生产环境请按域名白名单配置），或按需设置 Access-Control-Allow-Methods/Headers。
- 访问被防火墙拦截：在 CentOS 7/8 放行对应端口（如 38080/38081/3000），例如：
- 使用 firewalld：firewall-cmd --add-port=38080/tcp --permanent && firewall-cmd --reload
- 使用 iptables：iptables -A INPUT -p tcp --dport 38080 -j ACCEPT
- 文档无法加载：确认 swagger.json/swagger.yaml 路径可被访问（相对路径/绝对路径/HTTP URL 均可），必要时在 UI 中直接粘贴文档内容或修正 servers 配置。
- 鉴权失败：核对 token/key 是否过期、作用域是否匹配，以及请求头名称是否与后端约定一致。