패키지 상세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