Ubuntu上Swagger API如何测试

Ubuntu上Swagger API测试实操指南

一 准备环境

• 更新系统并安装 Node.js 与 npm（Swagger Editor/UI 基于 Node 生态）：
  • 命令：sudo apt update & & sudo apt install -y nodejs npm
• 可选：安装 Docker（便于用容器快速起 Swagger UI/Editor）：
  • 命令：sudo apt install -y docker.io
• 说明：Swagger 现已演进为 OpenAPI 规范，常见工具为 Swagger Editor（编辑/校验）与 Swagger UI（在线调试）。

二 方式一 使用Docker快速起Swagger UI

• 拉取镜像（示例使用 v4.15.5）：docker pull swaggerapi/swagger-ui:v4.15.5
• 启动容器（将本地 /path/to/swagger.yaml 挂载到容器内并指定服务器地址）：
  • 命令：

    docker run -d --name swagger-ui \
      -p 38081:8080 \
      -e SWAGGER_JSON=/spec/swagger.yaml \
      -v /path/to:/spec \
      swaggerapi/swagger-ui:v4.15.5
    

  • 访问：http://localhost:38081/swagger-ui.html
  • 提示：在 Swagger UI 的 Servers 处将服务器地址设置为你的后端地址（如 http://host.docker.internal:3000 或实际服务地址），否则可能请求到容器内部空地址。

三 方式二 在Node应用中集成Swagger UI

• 初始化项目并安装依赖：
  • 命令：mkdir swagger-demo & & cd swagger-demo & & npm init -y
  • 安装：npm i express swagger-ui-express yamljs
• 创建 swagger.yaml（示例）：

  openapi: 3.0.0
  info:
    title: Sample API
    version: 1.0.0
  servers:
    - url: http://localhost:3000
  paths:
    /users:
      get:
        summary: List all users
        responses:
          '200':
            description: OK
  

• 创建 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');
      
  app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
      
  app.get('/users', (req, res) =>
   res.json([{
   id: 1, name: 'Alice' }
      ]));
      
  const PORT = process.env.PORT || 3000;
      
  app.listen(PORT, () =>
   console.log(`Server on ${
  PORT}
      , /api-docs`));
      
  

• 启动与访问：
  • 启动：node index.js
  • 访问：http://localhost:3000/api-docs，在页面中点击 Try it out 发起请求。

四 方式三 使用Swagger Editor编辑与验证

• 下载并启动（示例版本 v3.16.1）：

  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
  npx http-server -p 8080
  

• 访问：http://localhost:8080，导入你的 swagger.yaml/swagger.json 进行校验与调试。
• 说明：Swagger Editor 主要用于编辑与校验规范，实际发起请求建议用 Swagger UI 或与后端联调。

五 常见问题与自动化测试

• 常见问题
  • 端口占用：更换 -p 端口或停止占用进程（如 lsof -i:8080）。
  • CORS 跨域：开发环境在后端启用 CORS；Swagger UI 容器场景优先用 host.docker.internal 指向宿主机服务。
  • 访问被拒绝：检查 防火墙/云安全组 是否放行对应端口（如 8080/3000/38081）。
  • 路径 404：确认后端服务已启动且 servers.url 配置正确；容器内外地址映射无误。
• 自动化测试示例（Node + Mocha + Supertest）
  • 安装：npm i -D mocha chai supertest yamljs
  • 测试脚本 test-swagger.js：

    const request = require('supertest');
        
    const app = require('./index');
     // 上面的 Express 实例
    const {
     expect }
         = require('chai');
        
    
    describe('GET /users', () =>
     {
        
      it('should return 200 and an array', async () =>
     {
        
        const res = await request(app).get('/users');
        
        expect(res.status).to.equal(200);
        
        expect(res.body).to.be.an('array');
    
      }
        );
    
    }
        );
        
    

  • 运行：npx mocha test-swagger.js
• 其他工具
  • 使用 swagger-tester（Python）对规范进行自动化校验与示例请求验证：
    • 安装：pip install swagger-tester
    • 使用：from swagger_tester import swagger_test; swagger_test(‘path/to/swagger.yaml’)。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！