Flutter OpenAPI Schema 生成插件openapi_schema_generator的使用

Flutter OpenAPI Schema 生成插件 openapi_schema_generator 的使用

openapi_schema_generator

openapi_schema_generator 是一个用于生成 OpenAPI 定义的工具。它仅支持定义的一个子集，并通过使用 freezed 包来建模数据，从而使得生成的代码更加易读。

安装

首先，你需要全局安装 openapi_schema_generator：

dart pub global activate openapi_schema_generator

使用

生成模型

假设你有一个 OpenAPI 定义文件 pets.json，你可以通过以下命令生成模型代码：

dart pub global run openapi_schema_generator:generate -o ./package/ ./definitions/pets.json

在项目中生成代码

进入生成的 package 文件夹，并运行以下命令以生成代码：

cd package
flutter pub get
flutter pub run build_runner build

定义规则

以下是使用 openapi_schema_generator 时需要遵循的一些规则：

  1. 所有模式都必须在 components.schema 中定义，并从子对象和路由中引用。
  2. 路由参数必须为基本类型（如 string、integer、number）。

常见问题解答 (FAQ)

为什么你不直接使用官方的 OpenAPI 生成器？

官方的 OpenAPI 生成器支持 Dart 语言，但在我看来，生成的代码过于复杂。它还会生成可变对象，这使得对象实例化不如简单的构造函数/copyWith 组合那么直观。

另一个原因是，对于 Dart 来说，目前还没有对 oneOf 的支持。相关问题。

什么是“opiniated”？

支持的定义子集仅设计用于满足我的需求。因此，可能有一些特定规则不符合你的 OpenAPI 定义方式。但这些限制允许我简化维护工作，因为我独自开发，且是在业余时间进行的。

我在哪里可以找到支持的定义示例和生成的代码？

你可以在 GitHub 仓库 中找到一个示例。

示例代码

pets.json 示例文件

{
  "openapi": "3.0.0",
  "info": {
    "title": "Pet Store API",
    "version": "1.0.0"
  },
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/pets/{id}": {
      "get": {
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

生成的代码示例

Pet.dart

// 生成的代码示例
import 'package:freezed_annotation/freezed_annotation.dart';

part 'pet.freezed.dart';
part 'pet.g.dart';

[@freezed](/user/freezed)
class Pet with _$Pet {
  const factory Pet({
    required int id,
    required String name,
    String? tag,
  }) = _Pet;

  factory Pet.fromJson(Map<String, dynamic> json) => _$PetFromJson(json);
}

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

1 回复

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


openapi_schema_generator 是一个用于 Flutter 的插件，它可以帮助你根据 OpenAPI 规范生成 Dart 数据模型和 API 客户端代码。这个插件可以大大简化与 RESTful API 交互的开发过程，特别是在你需要处理复杂的 API 响应和请求时。

安装 openapi_schema_generator

首先，你需要在 pubspec.yaml 文件中添加 openapi_schema_generator 作为开发依赖项：

dev_dependencies:
  openapi_schema_generator: ^1.0.0

然后运行 flutter pub get 来安装依赖。

使用 openapi_schema_generator

  1. 准备 OpenAPI 规范文件
    你需要有一个 OpenAPI 规范文件（通常是 openapi.yaml 或 openapi.json）。这个文件描述了你的 API 的结构，包括端点、请求参数、响应模型等。

  2. 配置生成器
    在项目的根目录下创建一个 build.yaml 文件，用于配置 openapi_schema_generator。以下是一个简单的配置示例：

    targets:
  $default:
    builders:
      openapi_schema_generator:
        options:
          input: "openapi.yaml"
          output: "lib/api"

    在这个配置中：

    • input 指定了 OpenAPI 规范文件的路径。
    • output 指定了生成的 Dart 代码的输出目录。

  3. 运行生成器
    在终端中运行以下命令来生成代码：

    flutter pub run build_runner build

    这将会根据 OpenAPI 规范文件生成 Dart 数据模型和 API 客户端代码，并将其输出到指定的目录中。

  4. 使用生成的代码
    生成的代码将包括数据模型和 API 客户端类。你可以在你的 Flutter 应用中使用这些类来与 API 进行交互。例如：

    import 'package:your_project/api/api.dart';

void fetchData() async {
  final api = ApiClient();
  final response = await api.getSomeData();
  print(response);
}

自定义生成器

openapi_schema_generator 提供了多种选项来自定义生成的代码。你可以在 build.yaml 文件中配置这些选项。以下是一些常见的配置选项：

  • generate_mocks: 是否生成模拟数据类。
  • use_null_safety: 是否生成支持空安全的代码。
  • generate_to_string: 是否为数据模型生成 toString 方法。

示例配置

targets:
  $default:
    builders:
      openapi_schema_generator:
        options:
          input: "openapi.yaml"
          output: "lib/api"
          generate_mocks: true
          use_null_safety: true
          generate_to_string: true
回到顶部