Flutter Swagger解析插件swagger_parser的使用

发布于 1周前 作者 itying888 来自 Flutter

Flutter Swagger解析插件swagger_parser的使用

Swagger Parser 简介

pub version pub likes dart style Star on Github Last commit on Github Tests

swagger_parser 是一个用于从OpenAPI定义文件或链接生成REST客户端和数据类的Dart包。它支持OpenApi v2, v3.0 和 v3.1版本，并且可以处理JSON和YAML格式的文件。

主要特性

  • 支持OpenApi v2, v3.0 和 v3.1
  • 支持JSON和YAML格式
  • 支持通过链接生成代码
  • 支持多种序列化器（如json_serializable、freezed、dart_mappable）
  • 支持多语言（Dart、Kotlin）
  • 提供Web界面：https://carapacik.github.io/swagger_parser

使用方法

安装

在你的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  swagger_parser:

dev_dependencies:
  build_runner: ^2.4.12
  json_serializable: ^6.9.0
  retrofit_generator: ^9.1.5

配置包

你可以在 pubspec.yaml 或创建一个新的配置文件 swagger_parser.yaml 中添加OpenAPI JSON文件的路径或URL。下面是一个示例配置：

swagger_parser:
  schema_path: schemes/openapi.json
  output_directory: lib/api
  name: PetStore
  language: dart
  json_serializer: json_serializable
  default_content_type: "application/json"
  root_client: true
  root_client_name: RestClient
  export_file: true
  put_in_folder: false
  put_clients_in_folder: false
  merge_clients: false
  client_postfix: Client
  path_method_name: false
  enums_to_json: false
  enums_parent_prefix: true
  unknown_enum_value: true
  mark_files_as_generated: true
  original_http_response: false
  replacement_rules:
    - pattern: "[0-9]+"
      replacement: ""
  skipped_parameters:
    - 'X-Some-Token'

对于多个方案，你可以这样做：

swagger_parser:
  output_directory: lib/api
  squash_clients: true
  schemes:
    - schema_path: schemes/openapi.json
      root_client_name: ApiMicroservice
      json_serializer: freezed
      put_in_folder: true
      replacement_rules: []

    - schema_url: https://petstore.swagger.io/v2/swagger.json
      name: pet_service_dart_mappable
      json_serializer: dart_mappable
      client_postfix: Service
      put_clients_in_folder: true
      put_in_folder: true

    - schema_url: https://petstore.swagger.io/v2/swagger
      name: pet_service
      client_postfix: Service
      put_clients_in_folder: true
      put_in_folder: true

    - schema_path: schemes/pet_store.json
      schema_url: https://petstore.swagger.io/v2/swagger.json
      output_directory: lib/api/kotlin
      language: kotlin

运行生成器

在包含 pubspec.yaml 文件的目录下运行以下命令来生成代码：

dart run swagger_parser

如果你使用了不同的配置文件名，请指定该文件：

dart run swagger_parser -f <path to your config file>

仅适用于 freezed 的构建

对于 freezed 和 retrofit 的组合，你需要在 build.yaml 文件中添加如下内容：

global_options:
  freezed:
    runs_before:
      - json_serializable
  json_serializable:
    runs_before:
      - retrofit_generator

然后运行以下命令进行代码生成：

dart run build_runner build

示例项目

假设我们有一个简单的Swagger文件 schemes/openapi.json，并希望将其转换为Flutter项目的REST客户端和模型类。以下是完整的步骤：

  1. 将Swagger文件放入项目中： 将 openapi.json 文件放入 schemes 目录下。

  2. 配置 pubspec.yaml： 添加上述配置到 pubspec.yaml 中。

  3. 运行生成命令： 执行 dart run swagger_parser 来生成代码。

  4. 检查生成的文件： 查看 lib/api 目录下的生成文件，确保客户端和模型类已正确生成。

通过这些步骤，你可以轻松地将Swagger文档转换为Flutter项目中的REST客户端和数据模型。


更多关于Flutter Swagger解析插件swagger_parser的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

Harmonyos Next教程
1 回复

更多关于Flutter Swagger解析插件swagger_parser的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html


当然，以下是一个关于如何在Flutter项目中使用swagger_parser插件来解析Swagger（OpenAPI）文档的示例代码。这个示例将展示如何加载和解析Swagger文档，并访问其中的一些基本信息。

首先，确保你已经在pubspec.yaml文件中添加了swagger_parser依赖：

dependencies:
  flutter:
    sdk: flutter
  swagger_parser: ^2.0.0  # 请检查最新版本号

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

接下来，在你的Flutter项目中创建一个Dart文件（例如swagger_service.dart），并编写以下代码来加载和解析Swagger文档：

import 'package:flutter/material.dart';
import 'package:swagger_parser/swagger_parser.dart';
import 'dart:convert';
import 'dart:typed_data';

class SwaggerService {
  static Future<OpenApi> loadAndParseSwagger(String url) async {
    // 使用HttpClient获取Swagger JSON文档
    final client = HttpClient();
    final request = await client.getUrl(Uri.parse(url));
    final response = await request.close();

    // 读取响应内容
    final Uint8List responseBodyBytes = await response.readBytes();
    final String responseBody = String.fromUtf8(responseBodyBytes);
    final Map<String, dynamic> responseBodyMap = jsonDecode(responseBody);

    // 使用swagger_parser解析Swagger文档
    final OpenApi openApi = await OpenApi.fromJson(responseBodyMap);

    // 关闭HttpClient
    client.close();

    return openApi;
  }
}

void main() async {
  // 示例Swagger文档URL
  final String swaggerUrl = 'https://petstore.swagger.io/v2/swagger.json';

  // 加载并解析Swagger文档
  final OpenApi openApi = await SwaggerService.loadAndParseSwagger(swaggerUrl);

  // 打印一些基本信息
  print('Swagger Info:');
  print('Title: ${openApi.info.title}');
  print('Version: ${openApi.info.version}');
  print('Paths:');
  openApi.paths.forEach((path, pathItem) {
    print('  $path:');
    pathItem.get?.operationId?.let((operationId) => print('    GET operationId: $operationId'));
    pathItem.post?.operationId?.let((operationId) => print('    POST operationId: $operationId'));
    // 可以根据需要添加对其他HTTP方法的处理
  });
}

注意：

  1. 上述代码中的main函数仅用于演示目的。在实际Flutter应用中，你可能需要在某个按钮点击事件或其他适当的地方调用SwaggerService.loadAndParseSwagger。
  2. swagger_parser插件的OpenApi类提供了丰富的API来访问Swagger文档中的各个部分，例如路径、定义、参数等。你可以根据需要进一步探索和使用这些API。

最后，确保你的Flutter项目已经正确配置并运行，然后你可以通过运行应用来查看控制台输出，验证Swagger文档是否已成功加载和解析。

回到顶部