Tonik #

A Dart code generator for OpenAPI specifications that produces complete, ready-to-use client code. Tonik handles the tricky parts other generators miss: oneOf/anyOf/allOf composition, multiple response content types or status codes, integer enums, schema names that clash with Dart built-ins (like Error or List), and proper encoding for all OpenAPI parameter styles.

Supported versions: OpenAPI 3.0 (full), 3.1 (partial/planned), 3.2 (partial/planned)

Motivation #

There are already numerous projects available to generate Dart code from OpenAPI documents. But all lack certain, most often critical features. They might not support integer enums, composable data types (oneOf, anyOf, allOf), fail if you use existing class names in Dart or dependencies (e.g. Response of dio) or handle only success responses.

This package aims to overcome these shortcomings.

Special thanks goes out to felixwoestmann, as this project would not have been possible without him.

Features and Documentation #

• Features Overview
• Configuration
• Data Types
• Composite Data Type
• Authentication
• Uri Encoding Limitations

Quick-Start Guide #

Installation #

Activate the tonik CLI via:

dart pub global activate tonik

Client Code Generation #

To generate client code you need the path to your OpenAPI specification file ready and define a name for the client package.

The package name should be snake_case following the official guidelines. The supplied API specification file can be written in json or yaml.

tonik --package-name=my_api_client --spec=path/to/openapi.[yaml|json]

Fore more information on how to configure the code generation see configuration.

Usage of Generated Code #

Add the generated package as a dependency to your project.

dart pub add "my_client_api:{path: path/to/package}"

Tonik generates an Api class per tag defined in the specification. To use the generated client, simply import it and create an instance.

Here we define a custom server URL (servers defined in the specification file are also available). Afterward we perform a network call. Finally, we check if the request was successful or failed.

import 'package:my_api_client/my_api_client.dart';

final api = PetApi(
  CustomServer(baseUrl: 'https://api.example.com'),
);

// Make API calls with type-safe responses
final response = await api.getPetById(petId: 1);
switch (response) {
  case TonikSuccess<GetPetByIdResponse>(:final value):
    print('Server response: $value');
  case TonikError():
    print('Network error occurred');
}

Take a look at the pet store integration tests. Furthermore check features for more information.

Changelog #

For a full list of changes of each release, refer to release notes.

Roadmap #

See roadmap