api_generator #

api_generator is a Dart CLI package for Flutter projects.

It helps you:

• create a generator-ready Flutter project structure
• connect the generator to an existing Flutter app
• generate Flutter code from Swagger/OpenAPI
• generate feature scaffolds from Swagger + Figma
• prepare a shared design-system foundation
• keep generated output organized inside one Flutter project

This package is made for practical everyday work. The goal is simple: give you commands that are easy to run, and output that is easy to continue working with.

Languages #

• English
• O'zbek
• Русский

What This Package Can Do #

1. Generate a Swagger-first Flutter structure #

Command:

api_generator generate <swagger-or-openapi-source>

What it supports as input:

• Swagger docs URL like https://example.com/docs
• direct OpenAPI JSON or YAML URL
• local openapi.json
• local swagger-ui-init.js

What it generates:

• app/
• core/
• shared/
• features/
• assets/

It can also:

• detect Swagger UI pages
• extract spec from swagger-ui-init.js
• ask for Basic Auth credentials when the source returns 401
• generate Retrofit + Dio client code
• generate Freezed request and response models
• generate repository, datasource, cubit, and page files

2. Start inside an existing Flutter app #

Command:

api_generator start

This is the quickest interactive flow when you already have a Flutter project and want guided setup.

3. Create a new generator-ready project #

Command:

api_generator init --project-name my_app --output /path/to/my_app

4. Attach to an existing Flutter project #

Command:

api_generator attach --project-root /path/to/my_flutter_app

5. Check project readiness #

Command:

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

6. Generate a feature from Swagger + Figma #

Command:

api_generator generate-feature \
  --swagger-url "https://example.com/docs" \
  --figma-url "https://www.figma.com/design/FILE_KEY/App?node-id=1-2" \
  --feature-name auth \
  --project-name my_app \
  --output /path/to/my_flutter_app/lib

7. Work with config, scan, assets, and widgets #

Available commands include:

• scan project
• config show
• config set
• sync design-system
• sync design
• sync api
• add-feature
• register-widget
• make-widget
• import-assets

Installation #

dart pub global activate api_generator

Check that it works:

api_generator --help

If you use Figma commands and need full access:

export FIGMA_ACCESS_TOKEN=your_figma_token

Fastest Ways To Start #

If you are already inside a Flutter project #

Run:

api_generator start

or run Swagger generation directly:

api_generator generate https://example.com/docs

If you want to generate into the current Flutter app manually #

Run:

api_generator generate https://example.com/docs ./lib

After generation:

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

Swagger/OpenAPI Support #

generate supports:

• Swagger docs page URL
• raw OpenAPI URL
• local OpenAPI file
• local Swagger UI init JS file

Auth support:

• no auth
• Basic Auth
• Bearer token

If the server requires Basic Auth and responds with 401, the CLI can prompt for username and password in the terminal.

Generated Output Style #

The Swagger-first flow generates a single Flutter project structure like this:

lib/
├─ main.dart
├─ app/
├─ core/
├─ shared/
└─ features/
   └─ feature_name/
      ├─ data/
      │  ├─ model/
      │  └─ repository/
      ├─ domain/
      │  ├─ data_source/
      │  └─ repository/
      └─ presentation/
         ├─ cubits/
         ├─ pages/
         └─ widgets/

Typical generated pieces:

• core/network/api_client.dart
• core/network/api_client.g.dart
• core/network/response_handler.dart
• core/network/server_error.dart
• core/api_constants.dart
• features/<feature>/data/model/...
• features/<feature>/domain/data_source/...
• features/<feature>/domain/repository/...
• features/<feature>/data/repository/...
• features/<feature>/presentation/cubits/...

Common Commands #

Safe Writing Modes #

The package supports these write modes:

• safe: create only new files
• merge: update supported files carefully
• force: overwrite when needed

Default mode is safe.

Example .codegen.yaml #

project_name: my_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

Notes #

• generate-feature can reuse .codegen.yaml if it already exists.
• generate is best when your main source of truth is Swagger/OpenAPI.
• generate-feature is best when you want Swagger + Figma together.
• Figma access may require a valid token and file permission.
• After generating Retrofit and Freezed files, run build_runner.

English #

What api_generator is #

api_generator is a command-line tool for Flutter projects. It helps you create project structure, generate code from Swagger/OpenAPI, and prepare feature scaffolds from Swagger + Figma.

When to use which command #

• Use start if you are already inside a Flutter project and want the easiest guided flow.
• Use init if you want to create a new project structure.
• Use attach if the Flutter project already exists and you want to connect generator config to it.
• Use doctor if you want to check whether the project is ready.
• Use generate if your main input is Swagger/OpenAPI.
• Use generate-feature if you want a feature scaffold from Swagger + Figma.

Easiest Swagger example #

api_generator generate https://example.com/docs

If you are already inside your Flutter project, this writes into ./lib.

If you want to choose the output manually:

api_generator generate https://example.com/docs /path/to/flutter_app/lib

Basic Auth example #

api_generator generate https://example.com/docs

If the server asks for Basic Auth, the CLI can prompt for:

• username
• password

After generation #

Run these commands inside your Flutter app:

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

O'zbek #

api_generator nima qiladi #

api_generator bu Flutter loyihalar uchun command-line tool. U loyiha strukturasi tayyorlashga, Swagger/OpenAPI’dan kod generatsiya qilishga, va Swagger + Figma asosida feature skelet yaratishga yordam beradi.

Qaysi buyruq qachon ishlatiladi #

• start: agar siz allaqachon Flutter project ichida bo'lsangiz va eng oson interactive yo'l kerak bo'lsa
• init: yangi project struktura tayyorlash uchun
• attach: mavjud Flutter projectga generator config ulash uchun
• doctor: project tayyormi yo'qmi tekshirish uchun
• generate: asosiy manba Swagger/OpenAPI bo'lsa
• generate-feature: Swagger + Figma asosida feature generatsiya qilish uchun

Eng oson Swagger misol #

api_generator generate https://example.com/docs

Agar terminal Flutter project ichida ochilgan bo'lsa, generator default holatda ./lib ichiga yozadi.

Agar output ni o'zingiz berishni xohlasangiz:

api_generator generate https://example.com/docs /path/to/flutter_app/lib

Basic Auth misol #

api_generator generate https://example.com/docs

Agar server Basic Auth so'rasa, CLI terminalda quyidagilarni so'rashi mumkin:

• username
• password

Generatsiyadan keyin #

Flutter project ichida:

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

Russian #

Что делает api_generator #

api_generator это command-line инструмент для Flutter проектов. Он помогает подготовить структуру проекта, сгенерировать код из Swagger/OpenAPI и создать каркас feature на основе Swagger + Figma.

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

• start: если вы уже находитесь внутри Flutter проекта и хотите самый простой интерактивный путь
• init: чтобы подготовить новую структуру проекта
• attach: чтобы подключить генератор к уже существующему Flutter проекту
• doctor: чтобы проверить готовность проекта
• generate: если основной источник это Swagger/OpenAPI
• generate-feature: если нужен feature scaffold из Swagger + Figma

Самый простой пример со Swagger #

api_generator generate https://example.com/docs

Если терминал уже открыт внутри Flutter проекта, генерация по умолчанию идёт в ./lib.

Если путь нужно указать вручную:

api_generator generate https://example.com/docs /path/to/flutter_app/lib

Пример с Basic Auth #

api_generator generate https://example.com/docs

Если сервер требует Basic Auth, CLI может спросить в терминале:

• username
• password

После генерации #

Внутри Flutter проекта выполните:

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