当前位置：首页 > news >正文

Swagger Client 迁移指南：从 2.x 到 3.x 的完整升级方案

news 2026/5/27 4:24:56

Swagger Client 迁移指南：从 2.x 到 3.x 的完整升级方案

【免费下载链接】swagger-jsJavascript library to connect to swagger-enabled APIs via browser or nodejs项目地址: https://gitcode.com/gh_mirrors/sw/swagger-js

Swagger Client 是一款强大的 JavaScript 库，可通过浏览器或 Node.js 连接到支持 Swagger 的 API。本指南将帮助开发者顺利完成从 2.x 到 3.x 版本的升级，掌握新特性并解决常见迁移问题。

📋 迁移前准备

在开始迁移前，请确保满足以下要求：

规范版本支持变化：3.x 版本已移除对 Swagger 1.0、1.1 和 1.2 规范的支持，仅支持 OpenAPI 2.0 及以上版本。若需继续使用旧规范，请保持 2.x 版本。
环境要求：确认项目已支持 Promise 和现代 JavaScript 特性，3.x 版本全面采用 Promise 替代回调函数。

🔑 核心变更与迁移步骤

1. 从回调函数到 Promise

旧代码（2.x）：

const client = new SwaggerClient({ success: () => { client.pet.addPet(...) }, failure: (err) => { console.error(err) } });

新代码（3.x）：

SwaggerClient({...}) .then(client => { client.apis.pet.addPet(...) }) .catch(error => { console.error(error) });

2. API 调用方式调整

旧代码（2.x）：

client.pet.findPetById({ petId: 3 }, (data) => { console.log(data.obj) }, (error) => { console.error(error) } );

新代码（3.x）：

client.apis.pet.findPetById({ petId: 3 }) .then(response => { console.log(response.body) }) // 响应体从 obj 改为 body .catch(error => { console.error(error) });

3. 标签接口访问路径变更

⚠️ 重要：3.x 版本中必须通过client.apis对象访问标签接口

旧代码（2.x）：

client.pet.findPetById(...); // 直接通过 client 访问标签

新代码（3.x）：

client.apis.pet.findPetById(...); // 通过 client.apis 访问标签

4. 授权方式更新

旧代码（2.x）：

const client = new Swagger('http://petstore.swagger.io/v2/swagger.json', { authorizations: { my_basic_auth: new PasswordAuthorization('foo', 'bar'), my_header_auth: new ApiKeyAuthorization('My-Header', 'bar', 'header') } });

新代码（3.x）：

SwaggerClient({ url: 'http://petstore.swagger.io/v2/swagger.json', authorizations: { my_basic_auth: { username: 'foo', password: 'bar' }, my_header_auth: 'bar', // 自动推断为 Header 类型 my_oauth2_token: { token: { access_token: 'abcabc' } } } }).then(client => { ... });

5. 默认 Content-Type 处理

3.x 版本不再默认设置Content-Type: application/json，如需保留此行为，可通过请求拦截器实现：

SwaggerClient({ url: "http://petstore.swagger.io/v2/swagger.json", requestInterceptor: req => { if (req.body && !req.headers["Content-Type"]) { req.headers["Content-Type"] = "application/json"; } } });