Effective Software Development using OpenAPI Generator

Modern startups are impossible to run without the right and smart approach to development. Properly configured and effective technologies can improve efficiency, increase productivity, thus resulting in a faster development process. 

‍

OpenAPI Generator refers to the generation of API client libraries, server stabs, documentation, and configuration that are automatically provided in an OpenAPI Spec.

Are you interested in developing software using OpenAPI Generator? If so, you’re in the right place. In this article, we will explain the most effective way to use OpenAPI Generator.

See our open positions

‍

What is OpenAPI Specification?

The OpenAPI Specification (or OAS) is a standardized interface that allows users (and even other services) to understand the capabilities of a service without prior knowledge of server implementation or access to the server code. This is possible because OAS clearly defines how the parameters for an API request or response should be defined without any ambiguity.

The OAS is generally produced in a YAML or JSON format and can be processed by tools like Redoc or Swagger to provide  user-friendly documentation. (More on OAS)

‍

OpenAPI Generators

One of the most repetitive tasks in the frontend application development cycle is integration with backend services. Any change on the backend needs to be appropriately reflected on the frontend for it to continue working properly. This means a frontend developer needs to analyze the backend changes and update their code accordingly. Sometimes, a small change on the backend leads to multiple changes on the frontend. This increases the risk of the frontend dev missing something and ultimately breaking the code.

‍

However, there is an easier way to do this. Most popular backend frameworks (like Django, Loopback, etc.) can generate an OpenAPI Specification for the service. Using the OAS, client side code can be generated.

‍

Currently, the OpenAPI Generator supports more than 50 client generators. In this article, we will use the OpenAPI Generator to generate client code for Dart, a backend service described by petstore.yaml.

‍

1. Installation

OpenAPIi generator provides multiple installation options based on the development environment and platform.

‍

After installation, you should be able to check the installation by performing the following operation: 

‍

‍

2. Usage

Once installed, you can use the following command to get a list of currently supported generators, based on your preferences.

‍

‍

The client library can be generated from the list generated in the previous command. In the example below, the client code for android is generated.

‍

‍

Parameters:

‍

• generate - Runs the generator and builds the code
• -g <generator-name> - Specifies the generator to be used
• -i <spec-file> - The input Openapi Specification file to be used for generating the file. This can be a URL or a local file.
• -o <output directory> - Indicates the location where the generated files will be stored.

‍

There are many more parameters that can be used to customize how the code is generated.

‍

3. Example

To maintain the scope of this article, we will be generating client code in Dart. We will use the dart-dio-next generator, which will - generate code in Dart - supports null safety - uses Dio to handle HTTP requests. - supports BuiltValue

‍

4. Setup

Once  the OpenAPI generator has been installed, we need an OpenAPI specification file that can be used to start generating code. As previously mentioned, we will use the petstore.yaml spec for this example.

For the rest of the article, I would also assume that the latest version of Dart is installed. You can find installation instructions here. We are using the  Dart SDK version: 2.13.4 (stable) for this example.

‍

Run generator

‍

‍

Generated files

Running the generate will create the folder specified by the -o parameter if it does not already exist. It will also add the following files into the folder.

‍

‍

• lib/src/auth/ - if Security definitions are provided in the OAS file, then the auth directory that handles authorisation is created.
• lib/src/model/ - contains Data Models for Schema Objects from the OAS. You will notice that these files have errors. This is because the dart-dio-next generator has created BuiltValue classes and expects us to generate the part files, which will be done in the following section.
• lib/src/api/ - contains the code for pet_api.dart, store_api.dart, and user_api.dart which integrates the backend API. These files are generated once for each tag in the OAS.
• test/ - contains stubbed test files for the API and Models
• README and doc/ - Documentation is generated for all the APIs and Models
• pubspec.yaml - The Dart package definition along with required dependencies

‍

5. Usage

To stabilise the project, we need to fetch all packages and run the build_runner.

‍

‍

Now that all our files have been generated, we can get a User by name very easily by running the following operation.

‍

‍

Successful software development using OpenAPI Generator - Wrapping up

It is clear that choosing the right tech stack is extremely important since it can substantially impact on the development time and product scalability.

OpenAPI generator, without a doubt,  greatly simplifies the process of backend integration. With just a few lines on the command line, you can generate well documented, easily testable and standardized code.

I hope this article helped you to understand the basic principles of the OpenAPI generator. If you want to develop custom software in record time, we are the right tech partner for you. Feel free to check our portfolio and what our clients have to say about us on Clutch.