Flutter OpenAPI自动生成与请求插件openapi_freezed_dio_builder的使用

Flutter OpenAPI 自动生成与请求插件 openapi_freezed_dio_builder 的使用

openapi_freezed_dio_builder 使用 Freezed 和 Dio 库来生成 Dart 客户端库，用于处理 OpenAPI 规范（目前只支持 YAML 文件）。

使用方法

  1. 更新 pubspec.yaml 文件：
dependencies:
  freezed: any
  json_annotation: ^3.0.1
  openapi_base: any

dev_dependencies:
  openapi_freezed_dio_builder: any
  json_serializable: ^3.3.0
  build_runner: ^1.10.0

  1. 在 lib 目录下创建一个以 .openapi.yaml 结尾的文件。你也可以使用符号链接。

  2. 可选：在你的规范文件中添加基础名称：

openapi: 3.0.0
info:
  x-dart-name: MyApiName
  1. 运行 build_runner：
(flutter) pub run build_runner build --delete-conflicting-outputs
  1. 实现客户端。（见下方）

支持的 OpenAPI 类型

不完全列表，除了标准模型和 API 端点之外：

  • 多部分请求
  • 自由形式定义
  • UUID 格式
  • 枚举

示例规范

以下是一个示例规范文件：

openapi: 3.0.0
info:
  version: 0.1.0
  title: 示例 API
  x-dart-name: TestApi

paths:
  /hello/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    get:
      summary: 向 {name} 问好
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelloResponse'
components:
  schemas:
    HelloResponse:
      properties:
        message:
          type: string
          description: 'Hello World 问候 ;-)'

实现客户端

import 'package:dio/dio.dart';
import 'package:openapi_freezed_dio_builder/api.dart';

Future<void> main() async {
  // 创建 Dio 实例并指定 API 基础 URL
  final client = Api(
    Dio(),
    Uri.parse('https://virtserver.swaggerhub.com/hpoul/Testapi/1.0.0'),
  );

  // 发送 GET 请求并获取响应
  final blubb = await client.helloNameGet(name: 'Blubb');
  print('Response: ${blubb.data}');
}

// 运行客户端示例
// dart run bin/example_client.dart

更多关于Flutter OpenAPI自动生成与请求插件openapi_freezed_dio_builder的使用的实战教程也可以访问 https://www.itying.com/category-92-b0.html

1 回复

更多关于Flutter OpenAPI自动生成与请求插件openapi_freezed_dio_builder的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


当然，下面是一个关于如何在Flutter项目中使用openapi_freezed_dio_builder插件来自动生成OpenAPI请求代码的示例。这个插件结合了OpenAPI规范、Freezed库和Dio库，可以大大简化API请求的处理。

步骤 1: 添加依赖

首先，你需要在pubspec.yaml文件中添加openapi_freezed_dio_builder和其他相关依赖：

dependencies:
  flutter:
    sdk: flutter
  dio: ^4.0.0

dev_dependencies:
  build_runner: ^2.0.0
  openapi_freezed_dio_builder: ^x.y.z  # 请替换为最新版本号
  freezed_annotation: ^x.y.z  # 请替换为与openapi_freezed_dio_builder兼容的版本号
  json_serializable: ^x.y.z  # 通常需要这个库来处理JSON序列化

步骤 2: 创建OpenAPI规范文件

假设你有一个名为api.yaml的OpenAPI规范文件，内容如下：

openapi: 3.0.0
info:
  title: 示例API
  version: 1.0.0
paths:
  /users:
    get:
      summary: 获取用户列表
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

步骤 3: 生成代码

在你的项目根目录下，运行以下命令来生成代码：

flutter pub run build_runner build --delete-conflicting-outputs

这个命令会根据api.yaml文件生成Dart代码，通常这些代码会被放在lib/generated目录下。

步骤 4: 使用生成的代码

生成的代码包括API客户端、数据模型等。你可以在你的Flutter应用中使用这些生成的代码来发起请求。

假设生成的API客户端名为ApiClient，你可以这样使用它：

import 'package:flutter/material.dart';
import 'package:dio/dio.dart';
import 'package:your_app/generated/api_client.dart'; // 根据实际路径调整

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: Text('OpenAPI Demo'),
        ),
        body: Center(
          child: FutureBuilder<List<User>>(
            future: fetchUsers(),
            builder: (context, snapshot) {
              if (snapshot.connectionState == ConnectionState.waiting) {
                return CircularProgressIndicator();
              } else if (snapshot.hasError) {
                return Text('Error: ${snapshot.error}');
              } else {
                return ListView.builder(
                  itemCount: snapshot.data?.length ?? 0,
                  itemBuilder: (context, index) {
                    return ListTile(
                      title: Text('${snapshot.data![index].name}'),
                      subtitle: Text('ID: ${snapshot.data![index].id}'),
                    );
                  },
                );
              }
            },
          ),
        ),
      ),
    );
  }

  Future<List<User>> fetchUsers() async {
    final apiClient = ApiClient(BaseOptions(baseUrl: 'https://your-api-base-url.com'));
    try {
      final response = await apiClient.usersGet();
      return response.data!;
    } catch (e) {
      throw e;
    }
  }
}

注意事项

  1. API基础URL：在创建ApiClient实例时，需要指定API的基础URL。
  2. 错误处理：在实际应用中，你可能需要更详细的错误处理逻辑。
  3. 依赖版本：确保所有依赖库的版本兼容，特别是openapi_freezed_dio_builder、freezed_annotation和json_serializable。

这个示例展示了如何使用openapi_freezed_dio_builder插件从OpenAPI规范自动生成API请求代码，并在Flutter应用中使用这些代码。希望这对你有所帮助！

回到顶部