Flutter OpenAPI代码生成插件openapi_code_builder的使用

openapi_code_builder 是一个用于生成服务器存根和客户端库的插件，它基于OpenAPI 3.0模式文件（目前仅支持YAML格式）。以下是关于如何使用 openapi_code_builder 的详细说明，并提供了一个完整的示例demo。

使用步骤

1. 更新 pubspec.yaml

首先，在你的项目的 pubspec.yaml 文件中添加必要的依赖项：

dependencies:
  json_annotation: ^3.0.1
  openapi_base: any

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

2. 创建OpenAPI模式文件

在 lib 文件夹中创建一个OpenAPI模式文件，文件扩展名为 .openapi.yaml。例如，创建一个名为 testapi.openapi.yaml 的文件：

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

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

3. 运行 build_runner

接下来，运行 build_runner 来生成Dart源文件：

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

4. 实现服务器和客户端

实现服务器

创建一个继承自生成的API类的实现类，并重写相应的方法。例如，创建一个 test_api_impl.dart 文件：

import 'package:openapi_base/openapi_base.dart';
import 'package:test_api/test_api.dart';

class TestApiImpl extends TestApi {
  @override
  Future<HelloNameGetResponse> helloNameGet({String name}) async {
    _logger.info('Saying hi to $name');
    return HelloNameGetResponse.response200(
        HelloResponse(message: 'Hello $name'));
  }
}

然后，创建一个服务器并绑定到端口。例如，创建一个 main_server.dart 文件：

import 'package:openapi_shelf/openapi_shelf.dart';
import 'package:test_api/test_api.dart';
import 'package:test_api_impl/test_api_impl.dart';
import 'package:logging/logging.dart';

Future<void> main() async {
  PrintAppender.setupLogging();
  _logger.fine('Starting Server ...');
  final server = OpenApiShelfServer(
    TestApiRouter(ApiEndpointProvider.static(TestApiImpl())),
  );
  await server.startServer();
}

实现客户端

创建一个客户端来调用API。例如，创建一个 main_client.dart 文件：

import 'package:logging/logging.dart';
import 'package:test_api/test_api.dart';
import 'package:http/http.dart' as http;

Future<void> main() async {
  final requestSender = HttpRequestSender(http.Client());
  final client = TestApiClient(
      Uri.parse('http://localhost:8000'),
      requestSender);
  final blubb = await client.helloNameGet(name: 'Blubb');
  blubb.map(
    on200: (response) => _logger.info('Success: ${response.body.message}'),
  );
  _logger.info('Response: $blubb');
  requestSender.dispose();
}

5. 运行示例

运行服务器

在项目根目录下运行以下命令启动服务器：

dart run bin/main_server.dart

运行客户端

在另一个终端窗口中运行以下命令启动客户端：

dart run bin/main_client.dart