Flutter Swagger代码生成插件 swagger_dart_code_generator 的使用

📣 构建 Dart 类型从 Swagger/OpenAPI 模式 📣

SwaggerDartCodeGenerator 是一个代码生成器，它查找 *.swagger 文件并基于模式构建 .swagger.dart 文件。代码生成基于 Chopper 和 JsonAnnotation 模型，并可以根据需要进行配置。

Overview

通常情况下，对于每个 .swagger 文件将创建三个输出：

• .dart：由 Swagger dart code generator 生成，包含所有模型、请求、转换器等。
• .enums.dart（自 v1.2.0）：由 Swagger dart code generator 生成，包含所有枚举和枚举映射。
• .chopper.dart：由 chopper 生成。
• .g.dart：由 json_serializable 生成。

Installation

生成的代码在运行时使用以下包：

dependencies:
  chopper: ^8.0.0
  json_annotation: ^4.8.0

为了能够进行代码生成，请将以下内容添加到您的 pubspec.yaml 文件中：

dev_dependencies:
  build_runner: ^2.3.3
  chopper_generator: ^8.0.0
  json_serializable: ^6.6.1
  swagger_dart_code_generator: ^2.10.4

然后运行：

dart pub get

或

flutter pub get

现在通过运行以下命令，SwaggerGenerator 将为您生成 API 文件：

dart run build_runner build

Configuration

Swagger 生成器提供了一些配置选项来生成代码。所有选项都应包含在项目根目录下的 build.yaml 文件中：

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          # 自定义配置选项!

配置选项

重要的是要记住，默认情况下，build 将遵循 Dart 的包布局约定，这意味着只有某些文件夹会被考虑解析输入文件。因此，如果您想引用其他文件夹中的文件，请确保您已在 sources 中包含了它：

targets:
  $default:
    sources:
      - lib/**
      - swagger_examples/**
      - swaggers/**

Default Value Map for Model Generation

如果您希望为特定类型的字段添加 defaultValue: 属性，可以使用默认值映射。请参阅以下示例：

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          input_folder: 'lib/swaggers'
          output_folder: 'lib/generated_code/'
          default_values_map:
            - type_name: int
              default_value: '36'
            - type_name: String
              default_value: 'default'
            - type_name: 'List<String>'
              default_value: '[]'
          exclude_paths:
            - '/cars/get'
          include_paths:
            - '/popular/cars'

Overriden Models Implementation

      swagger_dart_code_generator:
        options:
          input_folder: "input_folder/"
          output_folder: "lib/swagger_generated_code/"
          overriden_models:
            - file_name: "pet_service_json"
              import_url: "../overriden_models.dart"
              overriden_models:
                - "Pet"
                - "Order"
            - file_name: "pet_service_swagger"
              import_url: "../overriden_models_another.dart"
              overriden_models:
                - "Result"

Scalars Implementation

      swagger_dart_code_generator:
        options:
          input_folder: "input_folder/"
          output_folder: "lib/swagger_generated_code/"
          import_paths:
            - "package:uuid/uuid.dart"
          scalars:
            uuid:
              type: Uuid
              deserialize: Uuid.parse
              # 可选 - 默认是 toString()
              serialize: myCustomUuidSerializeFunction

Response Override Value Map for Requests Generation

如果您希望覆盖特定请求的响应，可以使用 response_override_value_map。例如：

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          input_folder: 'lib/swaggers'
          output_folder: 'lib/generated_code/'
          response_override_value_map:
            - url: '/store/inventory'
              method: get
              overridden_value: 'List<dynamic>'
            - url: '/news/latest'
              method: put
              overridden_value: 'MyPerfectType'

检查 示例 以详细了解如何使用它。

示例代码

import 'package:example/swagger_generated_code/pet_service_yaml.swagger.dart';

void main() async {
  final petsApi = PetServiceYaml.create();

  final postResult = await petsApi.petPost(
    body: Pet(
      name: 'Vovanella',
      photoUrls: [
        'https://i.ytimg.com/vi/hO6G8jxV-YU/maxresdefault.jpg',
        'https://i.ytimg.com/vi/5u3iv8AT8G8/maxresdefault.jpg'
      ],
      status: PetStatus.available,
      category: Category(),
    ),
  );

  final pet = Pet.fromJson(postResult.body as Map<String, dynamic>);

  print('Created pet id: ${pet.id}');
}

以上是 swagger_dart_code_generator 插件的详细使用说明，希望对您有所帮助！