Flutter OpenAPI集成插件openapi_dart_common的使用

Flutter OpenAPI集成插件openapi_dart_common的使用

简介

openapi_dart_common 是一个用于 Dart 客户端代码生成器的核心可重用库。它允许你从 OpenAPI 文件生成一个单一的客户端库，并在多个客户端中重用，例如 Flutter Web（浏览器）、Flutter 和 Dart CLI（如使用 Ogurets 进行端到端测试）。

如何使用

1. 添加依赖项

首先，在你的 pubspec.yaml 文件中添加 openapi_dart_common 和你生成的库依赖项：

dependencies:
  openapi_dart_common: ^3.2.1 
  your_generated_lib:
    path: ../your_generated_lib

2. 初始化 ApiClient

每个生成的服务都需要一个 ApiClient 实例。从版本 2.0 开始，我们已经切换到使用 Dio，它会自动处理浏览器和 CLI 的差异。因此，通常情况下你只需要指定 DioClientDelegate()，除非你需要覆盖 Dio 实例（例如提供额外的选项等）。

import 'package:openapi_dart_common/openapi.dart';
import 'package:dio/dio.dart';

void main() {
  // 创建 ApiClient 实例
  final _apiClient = ApiClient(
    basePath: "http://localhost:8903",  // API 的基础路径
    apiClientDelegate: DioClientDelegate(),  // 使用 DioClientDelegate
  );

  // 使用生成的服务
  final _personService = PersonServiceApi(_apiClient);

  // 调用服务方法
  _personService.getPerson(1).then((person) {
    print('Person: ${person.name}');
  }).catchError((error) {
    print('Error: $error');
  });
}

3. 自定义 BaseClient

如果你需要自定义 BaseClient，可以传递一个自定义的 BaseClient 实例给 ApiClient。但请注意，不要混合使用需要 dart:html（仅存在于浏览器中）和 dart:io（其他所有平台）的实现。

import 'package:openapi_dart_common/openapi.dart';
import 'package:dio/dio.dart';

class CustomClientDelegate extends DioClientDelegate {
  @override
  Dio createDioClient() {
    final dio = super.createDioClient();
    dio.options.connectTimeout = 5000;  // 设置连接超时时间
    dio.interceptors.add(LogInterceptor());  // 添加日志拦截器
    return dio;
  }
}

void main() {
  final _apiClient = ApiClient(
    basePath: "http://localhost:8903",
    apiClientDelegate: CustomClientDelegate(),
  );

  final _personService = PersonServiceApi(_apiClient);

  _personService.getPerson(1).then((person) {
    print('Person: ${person.name}');
  }).catchError((error) {
    print('Error: $error');
  });
}

Maven 配置

如果你没有安装 Maven，可以在 Linux 和 Mac 上通过包管理器（如 Homebrew）轻松安装。Maven 需要一个 JDK 实现，可以从 AdoptOpenJDK 获取。或者，你也可以使用 Docker 来运行 Maven。

完整示例 Demo

以下是一个完整的 Flutter 示例项目，展示了如何集成 openapi_dart_common 并使用生成的 API 服务。

1. 项目结构

flutter_openapi_demo/
├── lib/
│   ├── main.dart
│   └── services/
│       └── person_service.dart
├── pubspec.yaml
└── your_generated_lib/
    └── (生成的 API 代码)

2. pubspec.yaml

name: flutter_openapi_demo
description: A demo project for integrating openapi_dart_common in Flutter.

dependencies:
  flutter:
    sdk: flutter
  openapi_dart_common: ^3.2.1
  your_generated_lib:
    path: ../your_generated_lib
  dio: ^4.0.0

3. main.dart

import 'package:flutter/material.dart';
import 'package:openapi_dart_common/openapi.dart';
import 'package:dio/dio.dart';
import 'services/person_service.dart';

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

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter OpenAPI Demo',
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: PersonListScreen(),
    );
  }
}

class PersonListScreen extends StatefulWidget {
  @override
  _PersonListScreenState createState() => _PersonListScreenState();
}

class _PersonListScreenState extends State<PersonListScreen> {
  List<Person> _persons = [];

  @override
  void initState() {
    super.initState();
    _fetchPersons();
  }

  void _fetchPersons() async {
    try {
      final persons = await PersonService().getPersons();
      setState(() {
        _persons = persons;
      });
    } catch (e) {
      print('Error fetching persons: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Person List'),
      ),
      body: ListView.builder(
        itemCount: _persons.length,
        itemBuilder: (context, index) {
          final person = _persons[index];
          return ListTile(
            title: Text(person.name),
            subtitle: Text('ID: ${person.id}'),
          );
        },
      ),
    );
  }
}

4. services/person_service.dart

import 'package:openapi_dart_common/openapi.dart';
import 'package:dio/dio.dart';
import 'package:your_generated_lib/person_service_api.dart';  // 生成的 API 服务

class PersonService {
  final _apiClient = ApiClient(
    basePath: "http://localhost:8903",
    apiClientDelegate: DioClientDelegate(),
  );

  final _personService = PersonServiceApi(_apiClient);

  Future<List<Person>> getPersons() async {
    final response = await _personService.getPersons();
    return response.data;
  }
}