api_generator #

api_generator is a Dart CLI package that helps Flutter teams generate project scaffolds, design-system foundations, and feature code from Swagger/OpenAPI + Figma.

• English: It is designed to be simple for any Flutter developer and structured enough for real team projects.
• O'zbekcha: Paket istalgan Flutter dasturchi qiynalmasdan ishlata oladigan darajada sodda, lekin real jamoa loyihalari uchun yetarlicha tartibli.
• Русский: Пакет сделан так, чтобы им мог пользоваться любой Flutter-разработчик без лишней сложности, но при этом он подходит и для реальных командных проектов.

What It Can Do #

• create a new Flutter workspace with generator config
• attach safely to an existing Flutter project
• scan and validate project structure
• generate a shared design-system foundation from Figma
• generate a Flutter feature from Swagger/OpenAPI + Figma
• generate a Swagger-first single-project Flutter architecture scaffold
• register and reuse existing shared widgets
• import assets and prepare safe reports
• keep all generation behind safe, merge, and force write modes

Install #

dart pub global activate api_generator

If you want full Figma metadata access, provide a token:

export FIGMA_ACCESS_TOKEN=your_figma_token

Quick Start #

0. Fastest way inside an existing Flutter app #

If the Flutter project is already created and your terminal is open inside that project, run:

api_generator start

This interactive wizard will:

• ask for Figma URL
• ask you to choose an architecture
• install common Flutter packages
• prepare design-system notes
• generate a design-first feature scaffold
• run build_runner

1. Create a new project #

api_generator init \
  --project-name chakana_agent_app \
  --architecture clean \
  --state-management cubit \
  --networking dio \
  --dependency-injection get_it \
  --output /path/to/chakana_agent_app

This will:

• create a Flutter workspace unless you use --skip-flutter-create
• create .codegen.yaml
• create shared/theme/l10n/assets starter folders
• prepare the project for feature generation

2. Attach to an existing Flutter project #

api_generator attach \
  --project-root /path/to/existing_flutter_app \
  --architecture clean

Then check the project:

api_generator doctor --project-root /path/to/existing_flutter_app

3. Generate a feature from Swagger + Figma #

If your project already has .codegen.yaml:

api_generator generate-feature \
  --project-root /path/to/existing_flutter_app \
  --swagger-url "https://example.com/api/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=10-20" \
  --feature-name auth

If you want standalone generation without workspace config:

api_generator generate-feature \
  --swagger-url "https://example.com/api/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=10-20" \
  --feature-name auth \
  --project-name chakana_agent_app \
  --output /path/to/flutter_app/lib

4. Run code generation inside the Flutter app #

flutter pub run build_runner build --delete-conflicting-outputs

Command Guide #

How Figma Works #

• If the Figma URL contains a selected node-id, only that selected screen is used.
• If the URL is file-level or page-level, the generator tries to detect all screens related to feature-name.
• The generator looks at page names, frame names, sections, and nearby naming signals.
• If Figma metadata is unavailable, the package still creates the maximum safe Flutter scaffold and explains the missing pieces in the report.

How Swagger/OpenAPI Works #

• It supports Swagger docs URLs, direct OpenAPI JSON/YAML URLs, and local files.
• It extracts related endpoints by feature-name.
• It reads request bodies, response schemas, params, auth hints, and common pagination patterns.
• It groups endpoints into reusable feature use cases and generates Flutter-ready layers.
• It generates Retrofit + Dio clients plus Freezed request/response models without relying on openapi-generator-cli.

Safe Writing Modes #

• safe: create only new files, never overwrite existing ones
• merge: patch supported files when possible
• force: overwrite when needed

Default mode is safe.

Widget Registry #

If you already have shared widgets, register them once and reuse them later:

api_generator register-widget \
  --project-root /path/to/existing_flutter_app \
  --figma-component "Primary Button" \
  --flutter-path lib/shared/widgets/app_button.dart \
  --class-name AppButton

Then future generations will prefer AppButton instead of generating another duplicate button widget.

Example .codegen.yaml #

project_name: chakana_agent_app
project_mode: attach
architecture: clean
state_management: cubit
networking: dio
dependency_injection: getIt
model_codegen: freezedJson
localization: intl
theme_strategy: designTokens
paths:
  lib: lib
  features: lib/features
  shared: lib/shared
  theme: lib/theme
  assets: assets
  l10n: lib/l10n
  reports: .codegen/reports
merge_targets:
  router_file: lib/app/router/app_router.dart
  di_file: lib/app/di/service_locator.dart
  pubspec_file: pubspec.yaml
  localization_file: lib/l10n/app_en.arb
defaults:
  write_mode: safe
widget_registry:
  - figma_component: Primary Button
    flutter_path: lib/shared/widgets/app_button.dart
    class_name: AppButton

English #

Simple Flow #

1. Run init if you are starting a new app.
2. Run attach if the app already exists.
3. Run doctor to check your setup.
4. Run generate-feature with Swagger and Figma links.
5. Run build_runner in your Flutter app.

For the simplest terminal-first flow inside an existing app, just run api_generator start and paste a Figma URL.

When To Use Which Command #

• Use init for a new project.
• Use attach for an existing project.
• Use sync design-system when you want shared colors, typography, widgets, and assets first.
• Use add-feature when you want only the folder structure.
• Use generate-feature when you want the actual feature code from Swagger + Figma.

Practical Example #

api_generator attach \
  --project-root /Users/me/projects/chakana_agent_app \
  --architecture clean

api_generator generate-feature \
  --project-root /Users/me/projects/chakana_agent_app \
  --swagger-url "https://api.example.com/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=462-15781" \
  --feature-name auth

O'zbekcha #

Eng Oson Yo'l #

1. Yangi loyiha bo'lsa init ishlating.
2. Tayyor Flutter loyiha bo'lsa attach ishlating.
3. Hammasi joyidaligini tekshirish uchun doctor ishlating.
4. Keyin generate-feature bilan Swagger va Figma'dan feature yarating.
5. Oxirida Flutter loyihada build_runner yurgazing.

Eng sodda yo'l esa mavjud Flutter loyiha ichida api_generator start ishlatish.

Qaysi Buyruq Qachon Ishlatiladi #

• init: yangi loyiha ochish uchun
• attach: mavjud loyihaga generator ulash uchun
• sync design-system: shared rang, text style, widget va assetlarni tayyorlash uchun
• add-feature: faqat feature papka skeleti kerak bo'lsa
• generate-feature: real feature kodini chiqarish uchun

Amaliy Misol #

api_generator attach \
  --project-root /Users/me/projects/chakana_agent_app \
  --architecture clean

api_generator generate-feature \
  --project-root /Users/me/projects/chakana_agent_app \
  --swagger-url "https://api.example.com/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=462-15781" \
  --feature-name auth

Русский #

Самый Простой Путь #

1. Если проект новый, используйте init.
2. Если Flutter проект уже существует, используйте attach.
3. Проверьте состояние проекта через doctor.
4. Затем запустите generate-feature со ссылками Swagger и Figma.
5. В конце выполните build_runner внутри Flutter проекта.

Самый простой путь внутри уже готового Flutter проекта: api_generator start.

Когда Какую Команду Использовать #

• init: для нового проекта
• attach: для существующего проекта
• sync design-system: чтобы сначала подготовить общие цвета, типографику, виджеты и ассеты
• add-feature: если нужен только каркас feature
• generate-feature: если нужен готовый feature-код из Swagger + Figma

Практический Пример #

api_generator attach \
  --project-root /Users/me/projects/chakana_agent_app \
  --architecture clean

api_generator generate-feature \
  --project-root /Users/me/projects/chakana_agent_app \
  --swagger-url "https://api.example.com/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=462-15781" \
  --feature-name auth

Notes #

• generate-feature reuses workspace config when .codegen.yaml exists.
• Without .codegen.yaml, generate-feature falls back to standalone mode and requires --project-name.
• Basic auth and bearer auth are supported for Swagger sources.
• Figma access may require a valid token and file permissions.
• Generated Flutter projects may still need app-specific manual wiring for routing, DI, or assets when safe mode protects existing files.