Swagger Parser

Swagger Parser is a Dart package designed to automate the creation of REST clients and data classes from OpenAPI definition files or URLs. It supports OpenAPI versions v2, v3.0, and v3.1 in both JSON and YAML formats.

Key capabilities include:

• Generating REST client files based on the Retrofit pattern.
• Generating data classes using popular serializers: json_serializable, freezed, or dart_mappable.
• Supporting multiple target languages (Dart, Kotlin).
• Supporting Server-Sent-Events (SSE) in Dart.
• Providing a web interface at https://carapacik.github.io/swagger_parser for easier interaction.

Swagger Parser supports the following specifications and file formats:

OpenAPI Versions:

• OpenAPI v2
• OpenAPI v3.0
• OpenAPI v3.1

Input Formats:

• JSON
• YAML

Input Methods:

• Generation via a definition link (URL)
• Generation from a local file
• Support for multiple definitions in a single run

The tool generates code for both Dart and Kotlin. Depending on your target language, you can choose from several supported serialization libraries:

Dart Serializers:

• json_serializable
• freezed
• dart_mappable

Kotlin Serializers:

• moshi

All generated clients are based on the retrofit pattern.

To use swagger_parser to generate code from an OpenAPI/Swagger definition, follow these steps:

1. Add your schema: Place your Swagger/OpenAPI schema file in your project.
2. Configure pubspec.yaml:
   • Add the path to your schema file as an asset.
   • Set the desired output directory for the generated code.
3. Generate the parser output: Run the swagger_parser command to generate the initial REST clients and data classes.
4. Run build_runner: If you are using retrofit and freezed, run build_runner to complete the code generation for those specific libraries.

dart run swagger_parser
dart run build_runner build

To create a WebAssembly release compatible with GitHub Pages, use the flutter build web command with the --wasm and --release flags. Ensure you set the --base-href to /swagger_parser/ to match the GitHub Pages hosting path.

flutter build web --wasm --release --base-href /swagger_parser/

To develop or run the web interface locally using Flutter, use the following commands to fetch dependencies, analyze the code, run tests, and launch the application in Chrome.

flutter pub get
flutter analyze
flutter test
flutter run -d chrome

You can generate methods that return Stream types for SSE support. This is determined by the format and type in your OpenAPI specification.

• To generate Stream<Uint8List> (raw bytes): Set format: binary and type: integer.
• To generate Stream<String> (text): Set format: binary and type: string.

Example OpenAPI snippet for a byte stream:

paths:
  /pets:
    get:
      operationId: getBinaryStream
      responses:
        '200':
          description: Returns a stream of bytes.
          content:
            application/octet-stream:
              schema:
                type: integer
                format: binary

Results in:

@GET('/pets')
@DioResponseType(ResponseType.stream)
Stream<Uint8List> getBinaryStream();

When using freezed alongside retrofit, you must configure a build.yaml file to ensure the generators run in the correct order. The required execution sequence is: freezed $\rightarrow$ json_serializable $\rightarrow$ retrofit_generator.

global_options:
  freezed:
    runs_before:
      - json_serializable
  json_serializable:
    runs_before:
      - retrofit_generator

You can use the web-based interface to generate Dart and Kotlin clients directly in your browser. The configuration form in the web interface is designed to mirror every option available in the SWPConfig generation configuration. This allows for a visual way to configure your client generation without writing configuration files manually.

https://carapacik.github.io/swagger_parser

To use swagger_parser, add it to your dev_dependencies. Depending on your preferred JSON serializer (freezed, dart_mappable, or json_serializable), you must also include the corresponding runtime and generator dependencies in your pubspec.yaml.

dependencies:
  # Choose one of the following based on your preference:
  # dio: ^5.9.2
  # freezed_annotation: ^3.1.0
  # json_annotation: ^4.12.0
  # retrofit: ^4.9.2
  # dart_mappable: ^4.8.0

dev_dependencies:
  swagger_parser:
  # For freezed:
  # freezed: ^3.2.5
  # json_serializable: ^6.14.0
  # retrofit_generator: ^10.2.7
  # build_runner: ^2.15.0

  # For dart_mappable:
  # dart_mappable_builder: ^4.9.0

  # For json_serializable:
  # json_serializable: ^6.14.0
  # retrofit_generator: ^10.2.7
  # build_runner: ^2.15.0

If you are using freezed with retrofit, you must configure your build.yaml to ensure the correct generation order. The freezed generator must run before json_serializable, and json_serializable must run before retrofit_generator.

global_options:
  freezed:
    runs_before:
      - json_serializable
  json_serializable:
    runs_before:
      - retrofit_generator

Then run:

dart run build_runner build -d