パッケージ詳細v4.1.1

swagger_dart_code_generator

HTTPリクエストのコードを書くときに困っていませんか？このパッケージがお手伝いします。HTTPおよびモデルのコード生成機能がすべて揃っています。

AndroidiOSWebmacOSWindowsLinux

pub.dev API ドキュメントソースコード

30日間ダウンロード: 6.7万
いいね数: 335
Pub ポイント: 145

パッケージをインストール

flutter pub add swagger_dart_code_generator

パッケージ概要

公開情報に基づく選定ガイドです。参考としてご利用ください。

OpenAPI/Swagger仕様からHTTPクライアントコードとデータモデルを生成するFlutter/Dartパッケージです。タイプセーフなAPIクライアントの作成を自動化し、ボイラープレートを減らし、ネットワークリクエストのエラーを最小限に抑えます。SwaggerまたはOpenAPIで定義されたRESTful APIを使用する開発者にとって理想的であり、クリーンで保守しやすいDartコードを生成することで統合をスムーズにします。ジェネレーターはAndroid、iOS、Web、macOS、Windows、Linuxなど複数のプラットフォームをサポートしています。

用途

OpenAPI仕様からAPIクライアントの生成を自動化する
手動HTTPリクエストコードの削減
型安全性を活用したREST APIの統合
JSONスキーマからモデルを生成する
Flutterアプリにおけるバックエンド統合の最適化

主な機能

OpenAPI 2.0 および 3.0 の仕様から HTTP クライアントを生成します
型安全なDartモデルを生成します
カスタムヘッダーと認証をサポートしています
構成可能な出力構造を提供
Flutter ビルドシステムと統合されます

適している対象

OpenAPIで定義されたAPIを使用するFlutterチーム
API統合時間を短縮したい開発者
一貫性があり再利用可能なAPIクライアントを必要とするプロジェクト
コードの品質と保守性を重視するチーム

注意事項

有効な OpenAPI/Swagger 決定が必要です
API の変更時に手動での更新が必要です
静的コード生成に限定（実行時柔軟性なし）
バージョン管理されたAPI仕様と併用するのが最適です
複雑なエンドポイント用に追加の構成が必要になる場合があります

元の README

関連するソースリポジトリの README 原文のスナップショットです。最新の内容はリポジトリをご覧ください。

:mega: Build dart types from Swagger/OpenAPI schemas :mega:

SwaggerDartCodeGenerator is a code generator that looks for *.swagger files and builds .swagger.dart files, based on the schema. Code generation based on Chopper and JsonAnnotation models and can be configured for your needs.

Overview

In general case for each .swagger file three outputs will be created.
.dart generated by Swagger dart code generator, contains all models, requests, converters, etc.
[Since v1.2.0] .enums.dart generated by Swagger dart code generator, contains all enums and enums mappings.
.chopper.dart - generated by chopper.
.g.dart - generated by json_serializable.

Installation

The generated code uses the following packages in run-time:

dependencies:
  chopper: ^8.0.3
  json_annotation: ^4.9.0

Add the following to your pubspec.yaml file to be able to do code generation:

dev_dependencies:
  build_runner: ^2.4.9
  chopper_generator: ^8.0.3
  json_serializable: ^6.8.0
  swagger_dart_code_generator: ^3.0.1

Then run:

dart pub get

flutter pub get

Now SwaggerGenerator will generate the API files for you by running:

dart run build_runner build

Configuration

Swagger generator offers some configuration options to generate code. All options should be included on build.yaml file on the root of the project:

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          # custom configuration options!

Option	Default value	Is required	Description
`input_folder`	`-`	`true`	Path to folder with .swagger files (for ex. swagger_examples, or lib/swaggers).
`output_folder`	`-`	`true`	Path to output folder (for ex. lib/generated).
`input_urls`	`[]`	`false`	Here you can mention list of files to be downloaded from the internet. You can check example of usage.
`with_base_url`	`true`	`false`	If this option is false, generator will ignore base url in swagger file.
`use_required_attribute_for_headers`	`true`	`false`	If this option is false, generator will not add @required attribute to headers.
`with_converter`	`true`	`false`	If option is true, combination of all mappings will be generated.
`ignore_headers`	`false`	`false`	If option is true, headers will not be generated.
`additional_headers`	`false`	`false`	List of additional headers, not specified in Swagger. Example of usage: build.yaml
`enums_case_sensitive`	`true`	`false`	If value is false, 'enumValue' will be defined like Enum.enumValue even it's json key equals 'ENUMVALUE'
`include_paths`	`[]`	`false`	List of Regex If not empty - includes only paths matching reges
`exclude_paths`	`[]`	`false`	List of Regex If not empty -exclude paths matching reges
`classes_with_nullabe_lists`	[]	`false`	List of regex strings. If class name matches any of regex - list properties will have default value `null`. Otherwise it will be empty list. If you used `use_default_null_for_lists: true`, just set `.*` value for this property and result will be same. Check example for more details
`build_only_models`	`false`	`false`	If option is true, chopper classes will not be generated.
`separate_models`	`false`	`false`	If option true, generates models into separate file.
`include_if_null`	`null`	`false`	Sets includeIfNull JsonAnnotation feature and sets value for it. If null - not set anything.
`default_values_map`	`[]`	`false`	Contains map of types and theirs default values. See DefaultValueMap.
`response_override_value_map`	`[]`	`false`	Contains map of responses and theirs overridden values. See ResponseOverrideValueMap.
`cut_from_model_names`	`-`	`false`	If your model names are long and contain a lot of duplicated words, for example `DbUsersModelsV3GeneralUserModel`, you can cut off duplicated part, using `cut_from_model_names : DbUsersModelsV3`. Also, you can use regex expressions in this parameter.
`nullable_models`	`-`	`false`	List of model names should have force-nullable properties. Example of usage in build.yaml.
`override_equals_and_hashcode`	`-`	`true`	If need to decrease app size - you can disable generation of `hashcode` and `Equals` method.
`overriden_models`	`-`	`false`	List of manually written models that will replace the generated one. Can be different for each file. See example here
`use_path_for_request_names`	`true`	`false`	Can be false only if all requests has unique `operationId`. It gives readable names for requests.
`add_base_path_to_requests`	`false`	`false`	Add swagger base path to all request path.
`multipart_file_type`	`List<int>`	`false`	Allow to override the generated class for multipart file (See #605).
`override_to_string`	`bool`	`true`	Overrides `toString()` method using `jsonEncode(this)`
`generate_first_succeed_response`	`true`	`false`	If request has multiple success responses, first one will be generated. Otherwice - `dynamic`
`multipart_file_type`	`List<int>`	`false`	Type if input parameter of Multipart request
`scalars`	`-`	`{}`	A map of custom types that are used for string properties with a given format. See example here

It's important to remember that, by default, build will follow Dart's package layout conventions, meaning that only some folders will be considered to parse the input files. So, if you want to reference files from a folder other than lib/, make sure you've included it on sources:

targets:
  $default:
    sources:
      - lib/**
      - swagger_examples/**
      - swaggers/**

Default Value Map for model generation

If you want to add defaultValue: attribute to fields with concrete type you can use default value map. Please see next example:

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          input_folder: 'lib/swaggers'
          output_folder: 'lib/generated_code/'
          default_values_map:
            - type_name: int
              default_value: '36'
            - type_name: String
              default_value: 'default'
            - type_name: 'List<String>'
              default_value: '[]'
          exclude_paths:
            - '\/cars\/get'
          include_paths:
            - '\/popular\/cars'

Overriden Models Implementation

      swagger_dart_code_generator:
        options:
          input_folder: "input_folder/"
          output_folder: "lib/swagger_generated_code/"
          overriden_models:
            - file_name: "pet_service_json"
              import_url: "../overriden_models.dart"
              overriden_models:
                - "Pet"
                - "Order"
            - file_name: "pet_service_swagger"
              import_url: "../overriden_models_another.dart"
              overriden_models:
                - "Result"

Scalars Implementation

      swagger_dart_code_generator:
        options:
          input_folder: "input_folder/"
          output_folder: "lib/swagger_generated_code/"
          import_paths:
            - "package:uuid/uuid.dart"
          scalars:
            uuid:
              type: Uuid
              deserialize: Uuid.parse
              # optional - default is toString()
              serialize: myCustomUuidSerializeFunction

Response Override Value Map for requests generation

If you want to override response for concrete request, you can use response_override_value_map. For example:

targets:
  $default:
    builders:
      swagger_dart_code_generator:
        options:
          input_folder: 'lib/swaggers'
          output_folder: 'lib/generated_code/'
          response_override_value_map:
            - url: '/store/inventory'
              method: get
              overridden_value: 'List<dynamic>'
            - url: '/news/latest'
              method: put
              overridden_value: 'MyPerfectType'

Check the examples to see how to use it in details.

カテゴリー

OpenAPI & Swagger

依存関係

依存関係一覧 11 件

build^4.0.2
code_builder^4.11.0
collection^1.19.1
dart_style^3.1.2
http^1.5.0
json_annotation^4.9.0
markdown^7.3.0
path^1.9.1
recase^4.1.0
universal_io^2.2.2
yaml^3.1.3

ソースリポジトリ

epam-cross-platform-lab/swagger-dart-code-generator