Swagen - Swagger to Flutter Clean Architecture Generator

Swagen is a powerful code generator that converts Swagger/OpenAPI 3.0 specifications into a fully structured Flutter project following Clean Architecture principles.

With Swagen, you can automatically generate:

• Models & Entities
• Remote DataSources
• Repositories & Repository Implementations
• UseCases
• Providers
• GetIt Injector for dependency management

It supports Swagger v3 input from:

• Local JSON files (swagger.json)
• Local YAML files (swagger.yaml)
• Remote URLs (https://example.com/swagger.json)

Swagen simplifies the process of turning an API specification into a ready-to-use Flutter application with clean and maintainable architecture.

Usage

Swagen can be installed locally in a Flutter project or globally on your system. The usage differs slightly depending on the installation method.

Local Installation (Project-Specific)

Install Swagen in your Flutter project:

flutter pub add swagen

Run the generator using dart run:

Convert a local Swagger file

dart run swagen convert path/to/swagger.json

Convert from a URL

dart run swagen convert https://example.com/swagger.json

Features

1. Auto-generated Clean Architecture Layers

For each feature in your API, Swagen generates:

• Data Layer
  • Models for API responses
  • RemoteDataSource using http client and FlutterSecureStorage for token handling
  • RepositoryImpl implementing the feature repository interface
• Domain Layer
  • Entities representing your core business objects
  • Repository interface
  • UseCases encapsulating business logic
• Presentation Layer
  • Providers for state management (using ChangeNotifier)

2. Dependency Injection

• Generates a ready-to-use injector.dart with GetIt.
• All Providers, UseCases, Repositories, and DataSources are registered automatically.
• Supports lazy singletons for UseCases and Repositories and factories for Providers.

3. Security Support

• Handles Bearer Token authentication automatically.
• Uses FlutterSecureStorage to store JWT tokens securely.
• DataSource automatically attaches tokens to requests if configured.

4. HTTP Requests

• Uses http package for all API calls.
• Supports GET, POST, PUT, PATCH, DELETE methods.
• Automatically converts JSON responses into strongly typed Models and Entities.

5. Swagger / OpenAPI Support

• Accepts local .json file or URL.
• Supports:
  • Parameters (query, path, header)
  • Inline schemas
  • Nested entities
• Auto-generates method names and UseCases based on operationId or endpoint path.

Command

Swagen can generate a Flutter Clean Architecture project from a Swagger/OpenAPI file, either from a local JSON file or a remote URL. Below are the commands and explanations:

1. Generate from a local Swagger file

dart run swagen convert path/swagger.json

• dart run swagen convert → Runs the Swagen converter.
• path/swagger.json → Path to your local Swagger/OpenAPI JSON file.
• Generates models, entities, repositories, usecases, providers, and injector automatically.

2. Generate from a remote Swagger URL

dart run swagen convert https://example.com/swagger.json

• https://example.com/swagger.json → URL of the Swagger/OpenAPI JSON file.
• Useful if your API specification is hosted online.
• Everything else is generated the same as the local file command.

3. Specify a custom package name

dart run swagen convert swagger.json --package music_app

• --package music_app → Sets the package name used in import statements and generated code.
• Example: Instead of default package name from pubspec.yaml, it will use music_app in imports.

4. Generate Clean Architecture interactively

dart run swagen cleanarch

• Prompts you to enter the number of features in your API
• Asks for feature names one by one (e.g., auth, user, artist).
• Generates:
  • Data Layer: models, - datasources, repositories
  • Domain Layer: entities, repositories, usecases
  • Presentation Layer: providers

5. Help command

dart run swagen help

• Displays all available commands with explanations.

6. Swagger/Open API Support

Example Swagger:

{
  "openapi": "3.0.3",
  "info": {
    "title": "CineTrack API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://cinetrack-be.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "required": ["id", "email", "is_verified"],
        "properties": {
          "id": { "type": "string" },
          "email": { "type": "string" },
          "is_verified": { "type": "boolean" }
        }
      },
      "AuthResponse": {
        "type": "object",
        "required": ["message", "token", "user"],
        "properties": {
          "message": { "type": "string" },
          "token": { "type": "string" },
          "user": {
            "$ref": "#/components/schemas/User"
          }
        }
      }
    }
  },
  "paths": {
    "/api/login": {
      "post": {
        "tags": ["Auth"],
        "operationId": "loginUser",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}

Swagger Best Practice for Swagen:

• Use OperationId for Function Naming

  "operationId": "getMovieDetail"
  

  Generated Dart Function:

  Future<MovieDetail> getMovieDetail(int id)
  

• Use Tags for Separation

  "tags": ["Movies"]
  

  Generated Structure:

  features/movies/
  

• Use Components Schemas for All Model

  "$ref": "#/components/schemas/Movie"
  

  Benefits:
  • Reusable models
  • Automatic Entity + Model generation
  • Consistent structure across endpoints

7. Version command

dart run swagen version

• Displays the current version of Swagen.
• Shows the GitHub repository link for updates and issues.

Project Structure

After running Swagen, your Flutter project will have a clean architecture structure like this:

📦lib
 ┣ 📂core
 ┃ ┣ 📂error
 ┃ ┃ ┣ 📜exception.dart
 ┃ ┃ ┗ 📜failure.dart
 ┃ ┣ 📂injector
 ┃ ┃ ┗ 📜injector.dart
 ┃ ┗ 📂state
 ┃ ┃ ┗ 📜request_state.dart
 ┣ 📂features
 ┃ ┣ 📂auth
 ┃ ┃ ┣ 📂data
 ┃ ┃ ┃ ┣ 📂datasources
 ┃ ┃ ┃ ┃ ┗ 📜auth_remote_data_source.dart
 ┃ ┃ ┃ ┣ 📂models
 ┃ ┃ ┃ ┃ ┣ 📜auth_response.dart
 ┃ ┃ ┃ ┃ ┗ 📜user_response.dart
 ┃ ┃ ┃ ┗ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜auth_repository.dart
 ┃ ┃ ┣ 📂domain
 ┃ ┃ ┃ ┣ 📂entities
 ┃ ┃ ┃ ┃ ┣ 📜auth.dart
 ┃ ┃ ┃ ┃ ┗ 📜user.dart
 ┃ ┃ ┃ ┣ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜auth_repository.dart
 ┃ ┃ ┃ ┗ 📂usecases
 ┃ ┃ ┃ ┃ ┣ 📜login.dart
 ┃ ┃ ┃ ┃ ┗ 📜register.dart
 ┃ ┃ ┣ 📂presentation
 ┃ ┃ ┃ ┗ 📂providers
 ┃ ┃ ┃ ┃ ┣ 📜login_provider.dart
 ┃ ┃ ┃ ┃ ┗ 📜register_provider.dart
 ┃ ┃ ┗ 📜injector.dart
 ┃ ┣ 📂products
 ┃ ┃ ┣ 📂data
 ┃ ┃ ┃ ┣ 📂datasources
 ┃ ┃ ┃ ┃ ┗ 📜products_remote_data_source.dart
 ┃ ┃ ┃ ┣ 📂models
 ┃ ┃ ┃ ┃ ┗ 📜product_response.dart
 ┃ ┃ ┃ ┗ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜products_repository.dart
 ┃ ┃ ┣ 📂domain
 ┃ ┃ ┃ ┣ 📂entities
 ┃ ┃ ┃ ┃ ┗ 📜product.dart
 ┃ ┃ ┃ ┣ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜products_repository.dart
 ┃ ┃ ┃ ┗ 📂usecases
 ┃ ┃ ┃ ┃ ┣ 📜add_product.dart
 ┃ ┃ ┃ ┃ ┗ 📜get_product_by_id.dart
 ┃ ┃ ┣ 📂presentation
 ┃ ┃ ┃ ┗ 📂providers
 ┃ ┃ ┃ ┃ ┣ 📜add_product_provider.dart
 ┃ ┃ ┃ ┃ ┗ 📜get_product_by_id_provider.dart
 ┃ ┃ ┗ 📜injector.dart
 ┃ ┗ 📂users
 ┃ ┃ ┣ 📂data
 ┃ ┃ ┃ ┣ 📂datasources
 ┃ ┃ ┃ ┃ ┗ 📜users_remote_data_source.dart
 ┃ ┃ ┃ ┣ 📂models
 ┃ ┃ ┃ ┃ ┣ 📜user_list_response.dart
 ┃ ┃ ┃ ┃ ┗ 📜user_response.dart
 ┃ ┃ ┃ ┗ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜users_repository.dart
 ┃ ┃ ┣ 📂domain
 ┃ ┃ ┃ ┣ 📂entities
 ┃ ┃ ┃ ┃ ┗ 📜user.dart
 ┃ ┃ ┃ ┣ 📂repositories
 ┃ ┃ ┃ ┃ ┗ 📜users_repository.dart
 ┃ ┃ ┃ ┗ 📂usecases
 ┃ ┃ ┃ ┃ ┣ 📜create_user.dart
 ┃ ┃ ┃ ┃ ┗ 📜get_users.dart
 ┃ ┃ ┣ 📂presentation
 ┃ ┃ ┃ ┗ 📂providers
 ┃ ┃ ┃ ┃ ┣ 📜create_user_provider.dart
 ┃ ┃ ┃ ┃ ┗ 📜get_users_provider.dart
 ┣ ┗ ┗ 📜injector.dart