npm 包 swagger-axios 使用教程

npm 包 swagger-axios 是一个基于 Swagger API 规范的 API 客户端生成器，可以将 Swagger API 文档转化为可操作的 TypeScript 或 JavaScript 客户端。

安装

使用 npm 安装 swagger-axios：

npm install swagger-axios

使用

首先，需要将 Swagger API 文档导出为 JSON 或 YAML 文件。可以使用 Swagger UI 或 Swagger Editor 生成文档。

然后，将文档文件读取为一个 JSON 或 YAML 对象，并传递给 swagger-axios。

import { SwaggerAxios } from "swagger-axios";

import * as swaggerDocument from "./swagger.json";

const baseUrl = "http://api.example.com";

const swagger = new SwaggerAxios(swaggerDocument, baseUrl);

现在，你可以使用 swagger 对象调用 API。 swagger 对象包含每个端点的方法，以及 Swagger API 文档中定义的所有参数和返回值。

const response = await swagger.pet.getPetById({
  petId: 123,
});
console.log(response);

可操作的方法

每个端点都被包装在一个方法中，可以调用这个方法来执行请求。在方法中，可以传递所有参数，如在 Swagger API 文档中定义的。

一些有关可选参数的规则：

• query 参数必须是一个对象，它将序列化为查询字符串。
• body 参数必须是一个对象或字符串，它将作为请求体发送。
• path 参数必须是一个对象，表示在 URL 中包含的路径参数。
• form 参数必须是一个对象，它将序列化为表单数据。

const response = await swagger.pet.addPet({
  body: {
    id: 123,
    name: "Roger",
  },
});
console.log(response);

响应

SwaggerAxios 的响应对象是 AxiosResponse 的子类。可以通过访问 data 属性来获取响应的数据。

const response = await swagger.pet.getPetById({
  petId: 123,
});
console.log(response.data);

错误处理

当 API 返回错误响应时，SwaggerAxios 抛出一个包含错误信息的 Error 对象。可以使用 AxiosError 的 response 属性访问错误响应。

try {
  const response = await swagger.pet.deletePet({
    petId: 123,
  });
} catch (error) {
  console.error(error.response.data);
}

示例代码

下面是一个完整的示例，它使用 swagger-axios 调用 Swagger API。

-- -------------------- ---- -------
------ - ------------ - ---- ----------------

------ - -- --------------- ---- -----------------

----- ------- - -------------------------

----- ------- - --- ----------------------------- ---------

------ -- -- -
  --- -
    ----- -------- - ----- ------------------------
      ------ ----
    ---
    ---------------------------
  - ----- ------- -
    -----------------------------------
  -
-----

总结

swagger-axios 是一个强大的 Swagger API 客户端生成器，可以创建可读、可维护的 TypeScript 或 JavaScript 客户端。其中方法的可选参数可以满足 API 的所有需求。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60066b5751ab1864dac66cb7