Flutter Postman集合导入插件postman_collection的使用

Flutter Postman 集合导入插件 postman_collection 的使用

此插件是一个 Postman 集合模式生成器，允许您轻松为您的 Dio 和 http 客户端生成模式。

安装

要安装该包，只需运行以下命令：

dart pub add postman_collection

使用

要使用该包，您可以将其导入到项目中并调用 generateSchema 函数。以下是一个示例：

import 'package:postman_collection/postman_collection.dart';

PostmanCollection.fromJson(...);

示例代码

以下是一个完整的示例代码，展示了如何使用 postman_collection 插件生成 Postman 集合文件。

import 'dart:convert';
import 'dart:io';

import 'package:dio/dio.dart';
import 'package:yaml/yaml.dart';
import 'package:example/src/dio.dart';
import 'package:example/src/models.dart';
import 'package:postman_collection/postman_collection.dart';
import 'package:retrofit/retrofit.dart';

part 'main.g.dart';

class UploadFileResponse {
  final String url;

  UploadFileResponse({required this.url});

  factory UploadFileResponse.fromJson(Map<String, dynamic> json) {
    return UploadFileResponse(
      url: json['url'],
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'url': url,
    };
  }
}

[@RestApi](/user/RestApi)()
abstract class AppClient {
  factory AppClient(Dio dio, {String baseUrl}) = _AppClient;

  [@POST](/user/POST)('/upload')
  [@MultiPart](/user/MultiPart)()
  Future<HttpResponse<UploadFileResponse>> uploadFile(
    @Part() File file,
  );

  [@GET](/user/GET)('/app/{platform}')
  Future<HttpResponse<AppResponse>> getAppData({
    [@Path](/user/Path)() required String platform,
    @Header('Accept-Language') required String language,
    @Query('version') required String version,
    [@Body](/user/Body)() required AppDataRequestBody body,
  });
}

class AppClientDoc with PostmanCollectionDocumentationMixin {
  AppClientDoc(this._client);

  final AppClient _client;

  [@override](/user/override)
  Future<PostmanCollectionItem> doc() async {
    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromClass(runtimeType),
      item: await Future.wait([
        getAppDataDoc(),
        getUploadFileDoc(),
      ]),
    );
  }

  Future<PostmanCollectionItem> getAppDataDoc() async {
    final function = _client.getAppData;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(
          () => function(
            platform: 'android',
            version: '1.0.1',
            language: 'en',
            body: AppDataRequestBody(
              date: DateTime.now(),
            ),
          ),
        ),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(
            AppResponse(
              name: 'Postman',
              version: '1.0.0',
            ).toJson(),
          ),
        ),
        PostmanCollectionResponse(
          name: 'Error',
          status: '400',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(MessageResponse().toJson()),
        ),
      ],
    );
  }

  Future<PostmanCollectionItem> getUploadFileDoc() async {
    final function = _client.uploadFile;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(
          () => function(File('pubspec.yaml')),
        ),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode({
            'url': 'https://example.com/test.txt',
          }),
        ),
        PostmanCollectionResponse(
          name: 'Error',
          status: '400',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(MessageResponse().toJson()),
        ),
      ],
    );
  }
}

[@RestApi](/user/RestApi)()
abstract class UserClient {
  factory UserClient(Dio dio, {String baseUrl}) = _UserClient;

  [@GET](/user/GET)('/users/')
  Future<HttpResponse<List<UserResponse>>> get();

  [@GET](/user/GET)('/users/{id}')
  Future<HttpResponse<UserResponse>> getDetail([@Path](/user/Path)() String id);

  [@POST](/user/POST)('/users/')
  [@MultiPart](/user/MultiPart)() // 添加此注解以标记为 form-data
  Future<HttpResponse<UserResponse>> create([@Body](/user/Body)() CreateUserRequestBody body);

  [@PUT](/user/PUT)('/users/{id}')
  Future<HttpResponse<UserResponse>> update(
    [@Path](/user/Path)() String id,
    [@Body](/user/Body)() UpdateUserRequestBody body,
  );

  [@DELETE](/user/DELETE)('/users/{id}')
  Future<HttpResponse<UserResponse>> delete([@Path](/user/Path)() String id);
}

class UserClientDoc with PostmanCollectionDocumentationMixin {
  UserClientDoc(this._client);

  final UserClient _client;

  Future<PostmanCollectionItem> getDoc() async {
    final function = _client.get;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(function),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode([
            UserResponse(name: 'John Doe', email: 'johndoe@email.com'),
          ].map((e) => e.toJson()).toList()),
        )
      ],
    );
  }

  Future<PostmanCollectionItem> getDetailDoc() async {
    final function = _client.getDetail;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(() => function('1')),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(
            UserResponse(
              name: 'John Doe',
              email: 'johndoe@email.com',
            ).toJson(),
          ),
        )
      ],
    );
  }

  Future<PostmanCollectionItem> createDoc() async {
    final function = _client.create;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(
          () => function(
            CreateUserRequestBody(
              name: 'John Doe',
              email: 'asd',
              image: File("${Directory.current.path}/lib/src/dio.dart"),
            ),
          ),
        ),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(
            UserResponse(
              name: 'John Doe',
              email: 'asd',
            ).toJson(),
          ),
        )
      ],
    );
  }

  Future<PostmanCollectionItem> updateDoc() async {
    final function = _client.update;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(
          () => function(
            '1',
            UpdateUserRequestBody(
              name: 'John Doe',
              email: 'asd',
            ),
          ),
        ),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(
            UserResponse(
              name: 'John Doe',
              email: 'asd',
            ).toJson(),
          ),
        )
      ],
    );
  }

  Future<PostmanCollectionItem> deleteDoc() async {
    final function = _client.delete;

    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromFunction(function),
      request: PostmanCollectionRequest.fromRequestOptions(
        await getRequestOptionsFromRetrofit(() => function('1')),
      ),
      response: [
        PostmanCollectionResponse(
          name: 'Default',
          status: '200',
          postmanPreviewLanguage: 'json',
          body: jsonEncode(
            UserResponse(
              name: 'John Doe',
              email: 'asd',
            ).toJson(),
          ),
        )
      ],
    );
  }

  [@override](/user/override)
  Future<PostmanCollectionItem> doc() async {
    return PostmanCollectionItem(
      name: PostmanCollectionItem.getNameFromClass(runtimeType),
      item: await Future.wait([
        getDoc(),
        getDetailDoc(),
        createDoc(),
        updateDoc(),
        deleteDoc(),
      ]),
    );
  }
}

Future<void> main() async {
  final dio = getDocumentationDio();

  final pubspecYaml = loadYaml(File('pubspec.yaml').readAsStringSync());

  final projectName = pubspecYaml['name'];

  print('Generating Postman Collection for $projectName');

  final collection = PostmanCollection(
    info: PostmanCollectionInfo(
      name: projectName,
      schema: PostmanCollectionInfo.schemaV210,
      version: PostmanCollectionVersion.fromString('1.0.0'),
    ),
    item: await Future.wait([
      AppClientDoc(AppClient(dio)),
      UserClientDoc(UserClient(dio)),
    ].map((e) => e.doc()).toList()),
  );

  final file = File('versions/${PostmanCollection.filename(projectName)}');

  await file.writeAsString(jsonEncode(collection.toJson()));
  print('Postman Collection generated at ${file.path}');
}

String jsonEncode(Object? object) {
  return JsonEncoder.withIndent('  ').convert(object);
}