{"id":28043077,"url":"https://github.com/masreplay/swagger_to_dart","last_synced_at":"2025-07-14T16:36:59.812Z","repository":{"id":285603181,"uuid":"890235820","full_name":"masreplay/api_spec_to_dart","owner":"masreplay","description":"auto-generates type-safe API clients and models from Swagger OpenAPI, Postman, Support freezed, Union, dio and Retrofit","archived":false,"fork":false,"pushed_at":"2025-06-19T10:18:10.000Z","size":3663,"stargazers_count":11,"open_issues_count":5,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-19T11:26:59.136Z","etag":null,"topics":["fastapi","freezed","openapi","retrofit","swagger","union"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/swagger_to_dart","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/masreplay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-18T08:21:57.000Z","updated_at":"2025-06-19T10:18:13.000Z","dependencies_parsed_at":"2025-04-23T16:46:06.632Z","dependency_job_id":"a75f1731-0878-48eb-8826-c13959924bea","html_url":"https://github.com/masreplay/api_spec_to_dart","commit_stats":null,"previous_names":["masreplay/swagger_to_dart","masreplay/api_spec_to_dart"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/masreplay/api_spec_to_dart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masreplay%2Fapi_spec_to_dart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masreplay%2Fapi_spec_to_dart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masreplay%2Fapi_spec_to_dart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masreplay%2Fapi_spec_to_dart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masreplay","download_url":"https://codeload.github.com/masreplay/api_spec_to_dart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masreplay%2Fapi_spec_to_dart/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265319565,"owners_count":23746363,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","freezed","openapi","retrofit","swagger","union"],"created_at":"2025-05-11T15:51:27.338Z","updated_at":"2025-07-14T16:36:59.551Z","avatar_url":"https://github.com/masreplay.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swagger to Dart\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/masreplay/swagger_to_dart/main/docs/logo-dark.svg\" width=\"400\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/masreplay/swagger_to_dart/main/docs/logo-light.svg\" width=\"400\"\u003e\n    \u003cimg alt=\"Swagger to Dart logo\" src=\"https://raw.githubusercontent.com/masreplay/swagger_to_dart/main/docs/logo-light.svg\" width=\"400\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n[![Pub Version](https://img.shields.io/pub/v/swagger_to_dart.svg)](https://pub.dev/packages/swagger_to_dart)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\nA powerful Dart package that auto-generates type-safe API clients and models from OpenAPI specifications (Swagger). Currently optimized for OpenAPI 3.1.0 specifications.\n\n## Support\n\n- [FastAPI](https://fastapi.tiangolo.com/)\n- [NestJS](https://nestjs.com/)\n- [Spring Boot](https://spring.io/projects/spring-boot)\n- [AspNet Core](https://dotnet.microsoft.com/apps/aspnet)\n- [Flask](https://flask.palletsprojects.com/)\n- Any other framework that generates OpenAPI 3.1.0 specs with JSON format\n\n## Features\n\n- 🚀 Generates Dart models with [freezed](https://pub.dev/packages/freezed) for immutability and serialization\n- 🔄 Creates [retrofit](https://pub.dev/packages/retrofit) API clients for type-safe HTTP requests\n- 🧩 Supports nested objects, enums, and complex data structures\n- 📊 Handles query parameters, path parameters, and request bodies\n- 📝 Generates documentation comments from OpenAPI descriptions\n- 🌐 Fetch OpenAPI specifications directly from URLs (JSON format)\n- 💾 Automatically saves fetched specs locally\n- 🛠️ Customizable output with configuration options\n- ⚡ Supports FastAPI, NestJS, Spring Boot, and any other framework that generates OpenAPI 3.1.0 specs\n\n## Getting Started\n\n### Add dependencies\n\nFirst, add the required dependencies to your `pubspec.yaml` file:\n\n```yaml\ndependencies:\n  dio: ^x.x.x\n  retrofit: ^x.x.x\n  freezed_annotation: ^x.x.x\n  json_annotation: ^x.x.x\n\ndev_dependencies:\n  swagger_to_dart: ^x.x.x\n  build_runner: ^x.x.x\n  freezed: ^x.x.x\n  json_serializable: ^x.x.x\n  retrofit_generator: ^x.x.x\n```\n\nOr use Dart CLI to add the dependencies:\n\n```sh\ndart pub add dev:swagger_to_dart\ndart pub add dev:build_runner\n\ndart pub add freezed_annotation\ndart pub add dev:freezed\ndart pub add json_annotation\ndart pub add dev:json_serializable\n\ndart pub add dio\ndart pub add retrofit\ndart pub add dev:retrofit_generator\n```\n\n### Configure build order\n\nCreate a `build.yaml` file in your project root to ensure the correct build order:\n\n```yaml\nglobal_options:\n  freezed:\n    runs_before:\n      - json_serializable\n  json_serializable:\n    runs_before:\n      - retrofit_generator\n```\n\nUpdate the `analysis_options.yaml` file:\n\n```yaml\nlinter:\n  rules:\n    prefer_single_quotes: true\n\nanalyzer:\n  exclude:\n    # for retrofit and json_serializable\n    - \"**/*.g.dart\"\n    # for freezed\n    - \"**/*.freezed.dart\"\n\n  errors:\n    # for json_serializable\n    invalid_annotation_target: ignore\n```\n\n### Generate code from your OpenAPI specification\n\nThere are two ways to generate code from your OpenAPI specification:\n\n#### 1. Using the command line\n\n```sh\ndart run swagger_to_dart --input path/to/openapi.json --output lib/api\n```\n\n#### 2. Using a configuration file\n\nCreate a `swagger_to_dart.yaml` file in your project root:\n\n```yaml\nswagger_to_dart:\n  # You can use a local file path\n  input_directory: schema/swagger.json\n  output_directory: lib/src/gen\n  api_client_class_name: ApiClient\n  imports:\n    - import 'package:dio/dio.dart';\n  skipped_parameters:\n    - Accept-Language\n    - X-Language\n    - X-Platform\n\n  # Or you can use a URL to directly download the spec\n  # url: https://example.com/api/swagger.json\n```\n\nThen run:\n\n```sh\ndart run swagger_to_dart\n```\n\n### Run code generation\n\nAfter generating the API clients and models, run the build_runner to generate the necessary code:\n\n```sh\ndart run build_runner build --delete-conflicting-outputs\n```\n\n## Example Usage\n\n### 1. Define the OpenAPI specification location\n\nCreate a `swagger_to_dart.yaml` configuration file:\n\n```yaml\nswagger_to_dart:\n  input_directory: schema/swagger.json\n  output_directory: lib/src/gen\n  api_client_class_name: ApiClient\n  imports:\n    - import 'package:dio/dio.dart';\n  skipped_parameters:\n    - Accept-Language\n    - X-Language\n    - X-Platform\n```\n\n### 2. Generate code\n\nOnce you've set up your configuration file, run the following commands:\n\n```sh\n# First, generate the Dart code from your OpenAPI specification\ndart run swagger_to_dart\n\n# Then, generate the implementation with freezed, json_serializable, and retrofit\ndart run build_runner build --delete-conflicting-outputs\n```\n\n### 3. Use the generated code\n\n```dart\nimport 'package:dio/dio.dart';\nimport 'package:your_project/api/api.dart';\n\nvoid main() async {\n  final dio = Dio();\n\n  // Add interceptors for auth, logging, etc.\n  dio.interceptors.add(LogInterceptor(responseBody: true));\n\n  // Create API client\n  final userClient = UserApi(dio, baseUrl: 'https://api.example.com');\n\n  try {\n    // Use the generated API client\n    final users = await userClient.getUsers();\n    print('Users: ${users.map((u) =\u003e u.name).join(', ')}');\n\n    // Create a model instance\n    final newUser = User(id: '123', name: 'John Doe', email: 'john@example.com');\n\n    // Use the model in an API call\n    final createdUser = await userClient.createUser(newUser);\n    print('Created user: ${createdUser.name}');\n  } catch (e) {\n    print('Error: $e');\n  }\n}\n```\n\n## Configuration Options\n\nThe package configuration is defined in a `swagger_to_dart.yaml` file. Below is the complete structure based on the package's internal representation:\n\n```yaml\nswagger_to_dart:\n  # Optional: URL for directly downloading OpenAPI specification (JSON format)\n  url: https://example.com/api/swagger.json\n\n  # Path to your OpenAPI specification file (default: 'schema/swagger.json')\n  input_directory: schema/swagger.json\n\n  # Directory where generated files will be placed (default: 'lib/src/gen')\n  output_directory: lib/src/gen\n\n  # Name for the main API client class (default: 'ApiClient')\n  api_client_class_name: ApiClient\n\n  # Additional imports to include in generated files (default: [])\n  imports:\n    - import 'package:dio/dio.dart';\n\n  # Parameters to skip during generation (default: [])\n  skipped_parameters:\n    - Accept-Language\n    - X-Language\n    - X-Platform\n```\n\n### Configuration Fields Explained\n\n- **url**: Optional URL to download the OpenAPI specification directly (JSON format only)\n- **input_directory**: Path to your local OpenAPI/Swagger JSON file (defaults to 'schema/swagger.json')\n- **output_directory**: Where the generated Dart files will be placed (defaults to 'lib/src/gen')\n- **api_client_class_name**: Name of the main API client class that will be generated (defaults to 'ApiClient')\n- **imports**: Additional import statements to include in all generated files\n- **skipped_parameters**: HTTP headers or parameters that should be excluded from code generation\n\n### Example Usage\n\n#### Basic Configuration\n\n```yaml\nswagger_to_dart:\n  input_directory: schema/swagger.json\n  output_directory: lib/src/gen\n  api_client_class_name: ApiClient\n```\n\n#### Configuration with Remote Source\n\n```yaml\nswagger_to_dart:\n  url: https://petstore3.swagger.io/api/v3/openapi.json\n  output_directory: lib/src/gen\n  api_client_class_name: PetStoreClient\n  imports:\n    - import 'package:dio/dio.dart';\n    - import 'package:logger/logger.dart';\n```\n\n## Remote Schema Support\n\nYou can use a remote OpenAPI schema URL directly in the configuration:\n\n```yaml\nswagger_to_dart:\n  url: https://petstore3.swagger.io/api/v3/openapi.json\n  output_directory: lib/src/gen\n```\n\nOr reference multiple schemas:\n\n```yaml\nswagger_to_dart:\n  schemas:\n    - name: pet_api\n      input_directory: schema/pet_swagger.json\n      output_directory: lib/src/gen/pet\n    - name: user_api\n      input_directory: schema/user_swagger.json\n      output_directory: lib/src/gen/user\n```\n\n## Handling Breaking Changes\n\nWhen your API changes, you can use the following workflow to update your generated code:\n\n1. Update your OpenAPI specification\n2. Run `dart run swagger_to_dart`\n3. Run `dart run build_runner build --delete-conflicting-outputs`\n4. Check for breaking changes in your codebase and update as needed\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis package is available under the MIT License.\n\n## Acknowledgements\n\nThis package was inspired by and builds upon other great Dart packages including [freezed](https://pub.dev/packages/freezed), [retrofit](https://pub.dev/packages/retrofit), and [json_serializable](https://pub.dev/packages/json_serializable) and [FastAPI](https://fastapi.tiangolo.com/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasreplay%2Fswagger_to_dart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasreplay%2Fswagger_to_dart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasreplay%2Fswagger_to_dart/lists"}