Ubuntu Swagger测试API的方法

Ubuntu 上使用 Swagger 测试 API 的实用方法

一 准备与安装

• 更新系统并安装 Node.js 与 npm（用于本地托管 Swagger UI/Editor）：
  • 命令：sudo apt update && sudo apt install -y nodejs npm
  • 验证：node -v、npm -v
• 可选：安装 Docker（用于一键运行 Swagger 容器）：
  • 命令：sudo apt-get update && sudo apt-get install -y docker.io && sudo systemctl start docker && sudo systemctl enable docker
• 说明：Swagger UI 用于展示与“Try it out”测试，Swagger Editor 用于编写/导入 OpenAPI/Swagger 规范文件（YAML/JSON）。

二 三种快速部署方式

• Docker 运行 Swagger Editor（推荐）
  • 拉取并启动：docker pull swaggerapi/swagger-editor:v4.6.0
  • 运行：docker run -d -p 38080:8080 swaggerapi/swagger-editor:v4.6.0
  • 访问：http://localhost:38080
• Docker 运行 Swagger UI（推荐）
  • 拉取并启动：docker pull swaggerapi/swagger-ui:v4.15.5
  • 运行：docker run -d -p 38081:8080 swaggerapi/swagger-ui:v4.15.5
  • 访问：http://localhost:38081（在页面输入框填入你的 swagger.yaml/swagger.json URL 后 Explore）
• Node.js + Express 集成 Swagger UI（便于与自有服务同进程托管）
  • 初始化：mkdir swagger-demo && cd swagger-demo && npm init -y
  • 安装：npm install express swagger-ui-express yamljs
  • 创建 app.js：

    const express = require('express');
    const swaggerUi = require('swagger-ui-express');
    const YAML = require('yamljs');
    const swaggerDocument = YAML.load('./swagger.yaml'); // 你的规范文件
    const app = express();
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));
    const PORT = process.env.PORT || 3000;
    app.listen(PORT, () => console.log(`Server at http://localhost:${PORT}/api-docs`));
    

  • 启动：node app.js，访问：http://localhost:3000/api-docs
• 补充：也可下载 Swagger Editor/UI 发布包，用 http-server 静态托管后访问 http://localhost:8080/8081。

三 在 Swagger UI 中执行测试

• 基本流程
  • 打开 Swagger UI，在顶部输入或选择你的 API 定义文件（本地可通过服务器静态托管或 Docker 挂载方式提供）。
  • 在左侧选择接口，展开后点击 Try it out，填写 路径参数/查询参数/请求头/请求体，再点击 Execute 发送请求。
  • 在 Responses 区域查看状态码、响应体、耗时与响应头；可使用 Download 下载响应或 Copy as cURL 复制命令到终端复现。
• 参数与位置
  • 路径参数：如 /pet/{petId}，在路径中填写实际值。
  • 查询参数：在 Parameters 表格中填写键值对。
  • 请求头：在 Headers 中添加，如 Authorization: Bearer 。
  • 请求体：在 Request body 编辑器中填写 JSON/XML。
  • 注意：部分浏览器禁止修改的请求头（如 Cookie/Host）无法通过 UI 设置。
• 认证与授权
  • API Key：点击顶部 Authorize，选择 apiKey 类型并填写密钥。
  • OAuth2：在 Swagger UI 初始化时配置 clientId/secret/scopes 等，完成授权流程。
• 多文档与体验优化
  • 通过 urls 配置多个 API 文档并设定 primaryName。
  • 常用配置：deepLinking、displayRequestDuration、filter、tryItOutEnabled、persistAuthorization（持久化授权）。

四 常见问题与处理

• 跨域问题（CORS）
  • 现象：浏览器控制台出现跨域错误，Swagger UI 无法发送请求。
  • 处理：在后端开启 CORS（如响应头 **Access-Control-Allow-Origin: *** 等），或在 Swagger UI 使用 代理/请求拦截器 将请求转发到目标服务。
• 认证失败
  • 确认在 Authorize 中选择了正确的 认证方式 与 作用域，并确保 token/密钥 有效且未过期；必要时开启 persistAuthorization 避免刷新丢失。
• 无法发送请求或参数不可编辑
  • 检查：API 定义中该操作是否允许 Try it out、是否已点击激活编辑模式、参数是否为 readOnly、是否误用了浏览器受限请求头。
• 使用本机或远程后端
  • 若后端仅监听 127.0.0.1，Swagger UI（在容器内或浏览器中）将无法直连；需将后端改为监听 0.0.0.0 或通过 Docker 网络/端口映射 使目标端口可达。

五 进阶 在 Spring Boot 项目中集成并测试

• 添加依赖（示例为 Springfox Swagger 2）：

  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
  </dependency>
  <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
  </dependency>
  

• 配置类启用 Swagger（示例）：

  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
      @Bean
      public Docket webApiConfig() {
          return new Docket(DocumentationType.SWAGGER_2)
              .groupName("webApi")
              .apiInfo(apiInfo())
              .select()
              .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
              .paths(Predicates.not(PathSelectors.regex("/error.*")))
              .build();
      }
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
              .title("示例 API 文档")
              .description("接口定义与测试")
              .version("1.0")
              .build();
      }
  }
  

• 启动项目后访问：http://localhost:8080/swagger-ui.html，在页面中对接口执行 Try it out 测试。