Flutter Swagger Generator — package to save your time

Hello, developers! Today I want to tell you about the code generation package, named swagger_dart_code_generator. It will help you save a lot of time when working with API calls. Let’s start from the beginning.

Almost all mobile applications use internet access to receive some data. In Flutter it can be done in different ways. The most popular way — is to use http package. This package allows making any request you want. The negative aspect using this package — you need to write a lot of duplicated code and parse all data manually.

If you want to simplify your life — you can use code generation. Code generation is the regular thing when we are working with Dart and Flutter. Most of Flutter applications use json_serializable, freezed and other popular packages to rid of work, can be done by machine. There are also packages for requests generation, for example, chopper or dio. Using these packages, we rid of requests and serialization or deserialization implementation and it’s cool! But, anyway, you need to declare models and requests manually. It takes time and there is a chance to make mistake in, for example, in some string values.

To describe API service, developers often use Swagger. Swagger (or OpenAPI) allows describing the structure of APIs, so that machines can read them. We use it on our current project. Using swagger format, a developer can implement models, requests, and responses, but the developer needs to do this manually. And we raised an idea: what if we will generate all models and requests using our custom generator? Then we implemented the first version of our generator.

Our idea was to generate models and requests description and let other generators to complete the generation. For generation serialization and deserialization, we have chosen json_serializable and for generation requests we have chosen chopper. We already used these packages in production apps and we are sure these packages are stable. To summarise, we generated service.dart and service.enums.dart files, and then, using these files, other generators complete our job.

Our package is easy to use. To setup it, the developer needs only add it to dev_dependencies and create build.yaml file at the root of the project. In build.yaml developer needs to mention two required parameters: input_folder and output_folder. Also need to mention sources of generation. Then we can run flutter pub run build_runner build command to generate everything we need. So, build.yaml file can look like this:

targets:
  $default:
    sources:
      - input_folder/**
    builders:
      swagger_dart_code_generator:
        options:
          input_folder: "input_folder/"
          output_folder: "lib/swagger_generated_code/"

Note: You need to mention sources only if you want to use files not in lib/ directory.

After generation, we will have everything ready to use immediately. All models, enums, described in API will be connected to API requests. For example, for pet_service_yaml.json we will have PetServiceYaml class. We can create an instance of it and make a call. As you see, here we use not Objects, not dynamic objects, but models, like Pet, enums, like PetStatus, etc. It’s easy and comfortable to use. Please example check out for more info.

void main() async {
  final petsApi = PetServiceYaml.create();
  final postResult = await petsApi.petPost(
    body: Pet(
      name: 'Vovanella',
      photoUrls: [
        'https://i.ytimg.com/vi/hO6G8jxV-YU/maxresdefault.jpg',
        'https://i.ytimg.com/vi/5u3iv8AT8G8/maxresdefault.jpg'
      ],
      status: PetStatus.available,
      category: Category(),
    ),
  );
}

We support yaml and json formats of service files. Our generator has a lot of options to customize your generation. The full set of options is described in our README. Let me describe a few of them.

• If you don’t want to use chopper, you can use generate_only_models option. In this case, generator will generate only models with fromJson and toJson methods.
• If you don’t want to store your yaml or json files locally, you can use input_urls option to list urls, from which the generator should download files and generate them.
• You can use ignore_headers option to not generate, for example, authentication headers for each call and do this manually in the interceptor.

By the way, not only our package allows to generate code using swagger files. There are a few ways to do this. The first one is openapi_generator package on pub.dev. It’s powerful and generates code well. Why we do not use this package — because it’s not flexible enough. This generator generates package with all requests, but there is no way to modify them. Using our generator, you can use interceptors, converters, and other things to modify and customize your requests. The second way — is to use code generation, provided by Swagger portal. It generates not null-safe deprecated code with requests when all fields are Objects, so this generation does not make sense. Our generator is flexible and customizable, that’s why I love to use it.

To summarise, we support a lot of features. We fixed a lot of raised issues. We have 83% of popularity in pub.dev and more than 120 likes at this moment. It saves a lot of our time, and, I hope, a lot of time for other developers. So, if you use Swagger format for API description — our generator will save your time for real coding!

If you have any questions, proposals, or issues — please raise an issue on our github. It is the best communication channel for us. Thanks a lot, fo attention, and good luck in your beginnings!