最新亚洲精品国自产在线,亚洲在线免费免费观看视频,精品一区二区久久

一、什么是 Swagger OpenAPI 規范？

首先，我們要理解 Swagger 和 OpenAPI 規范的基本概念，因為它們是我們生成 TypeScript 類型的核心。

1. Swagger/OpenAPI 規范簡介

Swagger 是一個開源框架，它幫助開發者設計、構建、文檔化和使用 RESTful APIs。隨著 OpenAPI 規范（OAS）的發布，Swagger 成為了這個規范的實施工具之一。OpenAPI 規范通過一個 JSON 或 YAML 文件來描述一個 API 的詳細信息，包括請求方式（GET、POST 等）、路徑、參數、響應類型等。

OpenAPI 規范的核心目的是通過機器可讀的格式，使得開發者可以自動化地生成文檔、客戶端代碼和服務器端代碼。它不再局限于靜態的文檔展示，而是一個真正的交互式 API 規范。

舉個例子，假如你有一個如下的 API 文檔（Swagger 格式）：

openapi:?3.0.0
info:
??title:?Example?API
??version:?1.0.0
paths:
??/users:
????get:
??????summary:?Returns?a?list?of?users
??????responses:
????????'200':
??????????description:?A?list?of?users
??????????content:
????????????application/json:
??????????????schema:
????????????????type:?array
????????????????items:
??????????????????type:?object
??????????????????properties:
????????????????????id:
??????????????????????type:?integer
????????????????????name:
??????????????????????type:?string

這個文檔描述了一個簡單的 API?/users，它是一個?GET?請求，返回一個包含用戶信息的 JSON 數組。

二、TypeScript 與 OpenAPI 的結合：自動生成類型

通過將 OpenAPI 規范與 TypeScript 結合，開發者可以從 API 文檔自動生成接口定義、請求參數、響應類型等，從而使 API 的使用更簡單、規范，并且減少了手動編寫類型的工作量。你不再需要每次修改 API 時手動更新 TypeScript 類型，所有的類型和文檔都可以同步更新。

1. 需要的工具

我們需要以下工具來實現 OpenAPI 到 TypeScript 類型的生成：

Swagger Codegen 或 OpenAPI Generator：這些工具可以根據 OpenAPI 規范生成各種語言的客戶端代碼和類型定義。
TypeScript 相關工具：我們需要一些工具來生成 TypeScript 類型，并且集成到項目中。

2. 安裝 OpenAPI Generator

首先，安裝 OpenAPI Generator。這個工具可以從 OpenAPI 規范自動生成代碼和類型。

你可以通過 npm 或 yarn 安裝它：npm install @openapitools/openapi-generator-cli -g

或者通過 Homebrew 安裝：brew install openapi-generator

3. 生成 TypeScript 類型

接下來，我們使用?openapi-generator?從 Swagger/OpenAPI 規范生成 TypeScript 類型。假設我們已經有一個?swagger.yaml?文件，表示了 API 的定義。我們可以運行以下命令來生成 TypeScript 類型：

openapi-generator-cli?generate?-i?swagger.yaml?-g?typescript-fetch?-o?./generated

解釋一下這個命令：

-i swagger.yaml：指定輸入的 OpenAPI 規范文件（swagger.yaml）。
-g typescript-fetch：指定生成的代碼類型為 typescript-fetch，這是一個用于生成 TypeScript 客戶端代碼的模板。
-o ./generated：指定輸出目錄，生成的代碼將存放在 ./generated 目錄下。

執行這個命令后，./generated 文件夾下會生成 TypeScript 類型定義文件、API 客戶端代碼、請求方法等。我們可以直接在 TypeScript 項目中使用這些文件。

三、理解生成的 TypeScript 類型

在生成 TypeScript 類型后，你會看到類似這樣的代碼結構：

1. API 客戶端代碼

在?generated?文件夾中，生成的?ApiClient.ts?會包含所有的請求方法，例如：

export?class?UsersApi?{
??private?apiClient:?ApiClient;

??constructor(apiClient:?ApiClient)?{
????this.apiClient?=?apiClient;
??}

??public?async?getUsers():?Promise<User[]>?{
????const?response?=?await?this.apiClient.get('/users');
????return?response.data;
??}
}

在這個例子中，我們看到?UsersApi?類的?getUsers?方法，它調用了?apiClient.get('/users')?來發起 GET 請求。apiClient?是一個自動生成的 API 客戶端類，它會處理 HTTP 請求和響應。

2. TypeScript 類型

生成的 TypeScript 類型也會包括請求和響應的定義：

export?type?User?=?{
??id:?number;
??name:?string;
};

export?type?ApiResponse<T>?=?{
??data:?T;
??status:?number;
??message:?string;
};

這些類型使得我們可以更精確地管理 API 請求和響應的數據結構，并且通過 TypeScript 的類型檢查，確保我們的 API 調用和數據處理更加可靠。

四、集成到 Vue 項目中

現在，我們已經生成了 API 客戶端和相關類型，接下來將其集成到一個 Vue 3 + TypeScript 項目中。假設我們在 Vue 3 項目中需要獲取用戶列表并展示。

1. 安裝依賴

首先，確保你已經安裝了?axios?或?fetch?作為 HTTP 請求庫。你可以選擇使用?axios，因為它更靈活且易于使用。npm?install?axios

2. 使用生成的 API 客戶端

然后，在 Vue 組件中，導入生成的 API 客戶端，并使用它來調用 API。

<template>
??<div>
????<h1>Users?List</h1>
????<ul>
??????<li?v-for="user?in?users"?:key="user.id">{{?user.name?}}</li>
????</ul>
??</div>
</template>

<script?lang="ts">
import?{?defineComponent,?ref,?onMounted?}?from?'vue';
import?{?UsersApi?}?from?'./generated/ApiClient';
import?{?User?}?from?'./generated/Types';

export?default?defineComponent({
??name:?'UsersList',
??setup()?{
????const?users?=?ref<User[]>([]);

????const?usersApi?=?new?UsersApi(new?ApiClient());

????const?fetchUsers?=?async?()?=>?{
??????try?{
????????const?userList?=?await?usersApi.getUsers();
????????users.value?=?userList;
??????}?catch?(error)?{
????????console.error('Error?fetching?users:',?error);
??????}
????};

????onMounted(()?=>?{
??????fetchUsers();
????});

????return?{
??????users
????};
??}
});
</script>