ApiSorcery - Flutter Example

This is a Flutter cross-platform application that demonstrates API integration using ApiSorcery. It can be compiled to multiple platforms including iOS, Android, Web, Windows, macOS, Linux, and HarmonyOS.

Features

✅ User Management (CRUD operations)
✅ Search and Filter
✅ Pagination
✅ Form Validation
✅ Image Upload
✅ Status Management
✅ Type-safe API calls with ApiSorcery
✅ Multi-platform support (iOS, Android, Web, Desktop, HarmonyOS)

Tech Stack

Flutter 3.27.4 - Cross-platform UI framework
Dart 3.6.2 - Programming language
Castor Flutter - UI component library
Dio - HTTP client
ApiSorcery - API code generation
JSON Serialization - Type-safe JSON handling

Supported Platforms

📱 iOS
📱 Android
🌐 Web
💻 Windows
💻 macOS
💻 Linux
📱 HarmonyOS (OpenHarmony)

Prerequisites

Flutter SDK >= 3.27.4
Dart SDK >= 3.6.2
Node.js >= 22.0.0 (for ApiSorcery)
Platform-specific tools:
- iOS: Xcode
- Android: Android Studio
- HarmonyOS: DevEco Studio

Getting Started

1. Install Flutter Dependencies

flutter pub get

2. Generate API Client Code

npm run swagger

This will generate Dart API client code from the OpenAPI specification.

3. Run the Application

iOS

flutter run -d ios

Android

flutter run -d android

Web

flutter run -d chrome

Desktop (macOS/Windows/Linux)

flutter run -d macos    # macOS
flutter run -d windows  # Windows
flutter run -d linux    # Linux

HarmonyOS

flutter run -d ohos

Available Scripts

Flutter Commands

Command	Description
`flutter pub get`	Install dependencies
`flutter run`	Run in debug mode
`flutter build ios`	Build for iOS
`flutter build apk`	Build Android APK
`flutter build web`	Build for web
`flutter build macos`	Build for macOS
`flutter build windows`	Build for Windows
`flutter build linux`	Build for Linux
`flutter test`	Run tests
`flutter analyze`	Analyze code

ApiSorcery Commands

Command	Description
`npm run swagger`	Generate API client code

Project Structure

apisorcery_demo_flutter/
├── lib/
│   ├── apis/              # Auto-generated API code
│   │   └── auto/
│   │       └── demo/
│   │           ├── api_user.dart
│   │           ├── api_file.dart
│   │           └── models/
│   ├── pages/             # Application pages
│   │   └── user/          # User management pages
│   ├── widgets/           # Reusable widgets
│   ├── utils/             # Utility functions
│   ├── constants/         # Constants
│   └── main.dart          # Application entry
├── assets/                # Static assets
│   └── fonts/             # Custom fonts
├── android/               # Android platform code
├── ios/                   # iOS platform code
├── web/                   # Web platform code
├── windows/               # Windows platform code
├── macos/                 # macOS platform code
├── linux/                 # Linux platform code
├── ohos/                  # HarmonyOS platform code
├── .apisorceryrc.json        # ApiSorcery configuration
├── pubspec.yaml           # Flutter dependencies
└── package.json           # Node.js dependencies (for ApiSorcery)

API Configuration

The application uses ApiSorcery to generate type-safe API client code. Configuration is in .apisorceryrc.json:

{
  "application": {
    "language": "dart",
    "outputDir": "./lib/apis/auto"
  },
  "servers": [
    {
      "code": "demo",
      "token": "your_token",
      "version": 3,
      "enabled": true,
      "source": "https://apisorcery.com/demo-api/swagger-json"
    }
  ]
}

Dependencies

Main Dependencies (pubspec.yaml)

dependencies:
  flutter:
    sdk: flutter
  castor_flutter: ^1.0.6        # UI components
  dio: ^5.9.1                    # HTTP client
  json_annotation: ^4.9.0        # JSON serialization
  intl: ^0.19.0                  # Internationalization
  toastification: ^3.0.3         # Toast notifications
  flutter_slidable: ^4.0.0       # Slidable list items
  flutter_spinkit: ^5.1.0        # Loading indicators
  path_provider: ^2.1.5          # File system paths
  permission_handler: ^12.0.1    # Permissions

Dev Dependencies

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0          # Linting rules
  build_runner: ^2.4.14          # Code generation
  json_serializable: ^6.9.4      # JSON serialization

Development

Flutter Widget Structure

Flutter uses a widget-based architecture:

class UserListPage extends StatefulWidget {
  @override
  _UserListPageState createState() => _UserListPageState();
}

class _UserListPageState extends State<UserListPage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('User Management')),
      body: ListView.builder(
        itemBuilder: (context, index) {
          return UserListItem(user: users[index]);
        },
      ),
    );
  }
}

API Usage

import 'package:apisorcery_demo_flutter/apis/auto/demo/api_user.dart';

// Get paginated user list
final response = await ApiUser.getUserPaged(
  pagination: Pagination(page: 1, limit: 10),
  code: 'search-term',
);

// Create user
await ApiUser.addUser(
  UserAddRequest(
    code: 'user001',
    name: 'John Doe',
    email: 'john@example.com',
  ),
);

State Management

This project uses StatefulWidget for state management:

class _UserPageState extends State<UserPage> {
  List<User> users = [];
  bool isLoading = false;

  Future<void> loadUsers() async {
    setState(() => isLoading = true);
    try {
      final response = await ApiUser.getUserPaged();
      setState(() {
        users = response.results;
        isLoading = false;
      });
    } catch (e) {
      setState(() => isLoading = false);
      // Handle error
    }
  }
}

Platform-Specific Code

Use conditional imports for platform-specific code:

import 'package:flutter/foundation.dart' show kIsWeb;

if (kIsWeb) {
  // Web-specific code
} else if (Platform.isIOS) {
  // iOS-specific code
} else if (Platform.isAndroid) {
  // Android-specific code
}

Code Style

Follow Effective Dart guidelines
Use flutter analyze to check code quality
Format code with dart format
Use meaningful variable and function names

Building for Production

iOS

flutter build ios --release

Android

flutter build apk --release
flutter build appbundle --release  # For Google Play

Web

flutter build web --release
./deploy_web.sh  # Deploy script

Desktop

macOS

flutter build macos --release

Windows

flutter build windows --release

Linux

flutter build linux --release

HarmonyOS

flutter build ohos --release

HarmonyOS Support

This project includes special support for HarmonyOS (OpenHarmony):

HarmonyOS Dependencies

The project uses HarmonyOS-adapted Flutter plugins:

dependency_overrides:
  image_picker:
    git:
      url: https://gitee.com/openharmony-sig/flutter_packages.git
      path: packages/image_picker/image_picker
      ref: master

  path_provider:
    git:
      url: https://gitee.com/openharmony-sig/flutter_packages.git
      path: packages/path_provider/path_provider

  permission_handler_ohos:
    git:
      url: https://gitcode.com/openharmony-sig/flutter_permission_handler.git
      path: permission_handler_ohos
      ref: br_permission_handler_v11.3.1_ohos

Building for HarmonyOS

Install DevEco Studio
Configure HarmonyOS SDK
Build the project:
```
flutter build ohos --release
```

Testing

Run Tests

flutter test

Run Tests with Coverage

flutter test --coverage

Widget Tests

testWidgets('User list displays correctly', (WidgetTester tester) async {
  await tester.pumpWidget(MyApp());
  expect(find.text('User Management'), findsOneWidget);
});

Deployment

iOS App Store

Build release version: flutter build ios --release
Open ios/Runner.xcworkspace in Xcode
Archive and upload to App Store Connect

Google Play Store

Build app bundle: flutter build appbundle --release
Upload to Google Play Console
Complete store listing and publish

Web Deployment

flutter build web --release
./deploy_web.sh

The built files will be in build/web/.

Troubleshooting

Common Issues

Dependencies Error
```
flutter clean
flutter pub get
```

Build Failed

flutter clean
rm -rf build/
flutter pub get
flutter build <platform>

Platform-Specific Issues
- iOS: Check Xcode version and CocoaPods
- Android: Check Android SDK and Gradle
- HarmonyOS: Check DevEco Studio and SDK
API Connection Issues
- Verify backend service is running
- Check API base URL configuration
- Verify network permissions in platform manifests

Platform Permissions

iOS (Info.plist)

<key>NSPhotoLibraryUsageDescription</key>
<string>Need photo library access to upload avatar</string>
<key>NSCameraUsageDescription</key>
<string>Need camera access to take photos</string>

Android (AndroidManifest.xml)

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Performance Optimization

Tips

Use const constructors for widgets that don't change
Implement ListView.builder for long lists
Use cached network images for better performance
Minimize rebuilds with proper state management
Profile your app with Flutter DevTools

Build Optimization

flutter build <platform> --release --split-debug-info=./debug-info --obfuscate

Name		Name	Last commit message	Last commit date
.fvm		.fvm
.vscode		.vscode
android		android
assets/fonts		assets/fonts
ios		ios
lib		lib
linux		linux
macos		macos
ohos		ohos
test		test
web		web
windows		windows
.apisorceryrc.json		.apisorceryrc.json
.gitignore		.gitignore
.metadata		.metadata
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
README.md		README.md
analysis_options.yaml		analysis_options.yaml
deploy_web.sh		deploy_web.sh
package.json		package.json
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Latest commit

History

Folders and files

Repository files navigation

ApiSorcery - Flutter Example

Features

Tech Stack

Supported Platforms

Prerequisites

Getting Started

1. Install Flutter Dependencies

2. Generate API Client Code

3. Run the Application

iOS

Android

Web

Desktop (macOS/Windows/Linux)

HarmonyOS

Available Scripts

Flutter Commands

ApiSorcery Commands

Project Structure

API Configuration

Dependencies

Main Dependencies (pubspec.yaml)

Dev Dependencies

Development

Flutter Widget Structure

API Usage

State Management

Platform-Specific Code

Code Style

Building for Production

iOS

Android

Web

Desktop

macOS

Windows

Linux

HarmonyOS

HarmonyOS Support

HarmonyOS Dependencies

Building for HarmonyOS

Testing

Run Tests

Run Tests with Coverage

Widget Tests

Deployment

iOS App Store

Google Play Store

Web Deployment

Troubleshooting

Common Issues

Platform Permissions

iOS (Info.plist)

Android (AndroidManifest.xml)

Performance Optimization

Tips

Build Optimization

Resources

Official Documentation

UI Components

Platform-Specific

Version Information

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages