生成客户端API代码 - Medium

生成客户端 API 代码的完整指南

在前端和OpenAPI Generator 项目生成客户端 API 代码，并以 React 项目为例，展示具体的实现步骤。

什么是 OpenAPI Generator？

OpenAPI 规范生成 API 代码。它支持多种编程语言和框架，既可以生成服务器端代码，也可以生成客户端代码。本文将重点介绍 Typescript Axios 生成器的使用方法。

准备工作

在开始之前，请确保以下条件已经满足：

您的计算机上已安装 NPM 和 Node.js。
拥有一个 OpenAPI 规范文件（可以使用示例文件）。

本文将以 React 项目为例，但 OpenAPI Generator 与具体框架无关，您可以在任何框架中使用它。

创建 React 项目

首先，创建一个配置为使用 Typescript 和 SWC 作为编译器的 React 项目。运行以下命令：

npm create vite@latest open-api-generator-react-project -- --template react-swc-ts

等待项目创建完成后，进入项目目录并安装依赖：

cd open-api-generator-react-project && npm install

打开项目后，您将看到一个基础的 React 项目结构。我们无需修改 UI 组件，因为本文的重点是 API 代码的生成和使用。

安装 OpenAPI Generator CLI

接下来，将 OpenAPI Generator CLI 安装到项目中：

npm install @openapitools/openapi-generator-cli

提示：您也可以选择全局安装 CLI 或使用 Docker 运行生成器，具体方法请参考官方文档。

项目结构调整

在项目的 src 文件夹中，创建一个名为 api 的目录。在 api 目录下再创建一个 specifications 文件夹，用于存放 OpenAPI 规范文件。最终的目录结构如下：

src/

  └── api/

      └── specifications/

          └──

将您的 OpenAPI 规范文件放入 specifications 文件夹中。

配置生成器

在项目根目录下创建一个配置文件 openapitools.json，并添加以下内容：

{
  "generator-cli": {
    "version": "6.0.0"
  },
  "typescript-axios": {
    "useSingleRequestParameter": true,
    "modelPropertyNaming": "camelCase",
    "supportsES6": true
  }
}

说明：

useSingleRequestParameter：将所有方法的参数封装为一个对象，便于管理。

其他配置项可根据需要调整，具体请参考官方文档。

生成 API 代码

运行以下命令生成 API 代码：

npx openapi-generator-cli generate

如果一切顺利，您将在 src/api 目录下看到生成的代码文件。

清理多余文件

生成的代码中可能包含一些不必要的文件。您可以手动删除这些文件，也可以使用脚本自动清理。在项目根目录创建一个名为 generate-api.sh 的脚本文件，内容如下：

#!/bin/bash
# 清理多余文件的脚本
rm -rf src/api/specifications/*.bak

将脚本添加为 package.json 的运行命令：

"scripts": {
  "gen-api": "chmod +x generate-api.sh && ./generate-api.sh"
}

运行以下命令执行脚本：

npm run gen-api

初始化 API 实例

生成的代码可以直接使用，但每次初始化 API 类都需要传递配置参数，这可能会导致内存浪费。为了解决这个问题，我们可以创建一个上下文提供程序来管理 API 实例。

创建上下文提供程序

在 src/contexts 目录下创建一个 user-api-context.tsx 文件，内容如下：

import React, { createContext, useContext } from 'react';
import { Configuration, UserApi } from '../api/UsersAPI_V1';

const ApiContext = createContext(null);export const ApiProvider: React.FC = ({ children }) => {
  const config = new Configuration({ basePath: 'https://api.example.com' });
  const apiInstance = new UserApi(config);  return {children};
};export const useApi = () => {
  const context = useContext(ApiContext);
  if (!context) {
    throw new Error('useApi must be used within an ApiProvider');
  }
  return context;
};

在主入口文件中使用提供程序

修改 main.tsx 文件，将 ApiProvider 包裹在应用组件外层：

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import './index.css';
import App from './App.tsx';
import { ApiProvider } from './contexts/user-api-context.tsx';

createRoot(document.getElementById('root')!).render(
  
    
      
    
  
);

总结

通过本文的步骤，您可以轻松地使用 OpenAPI Generator 生成客户端 API 代码，并在 React 项目中高效地管理和使用这些代码。通过上下文提供程序的方式，我们可以确保 API 实例的复用，从而优化内存使用。

如果您在操作过程中遇到问题，欢迎留言讨论！

原文链接: https://medium.com/@devriesrjj/generating-front-end-api-code-2517b8d89b26