Skip to content

Tool used to generate api.video's API clients, based on OpenAPI codegen

License

Notifications You must be signed in to change notification settings

apivideo/api.video-api-client-generator

Repository files navigation

badge   badge   badge

api.video API client generator

api.video is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

Table of contents

Project description

API client generation tool based on OpenAPI Generator. Generates client source code in several languages based on mustache templates.

Getting started

Requirements

  • Java 1.8+
  • Maven

Usage

To generate an API client:

mvn package -P [profile]

To see the list of available profiles, see the "profile" column in the table of supported languages.

Documentation

Supported languages

Language Profile CI tests CI package release Repository
Java java java-api-client
Android android android-api-client
Android android-uploader android-video-uploader
NodeJs/Typescript nodejs nodejs-api-client
Php php - php-api-client
C# csharp csharp-api-client
Go go - go-api-client
Python python python-api-client
Swift5 swift5 ios-api-client
Swift5 swift5-uploader ios-video-uploader

Template files

Mustache template files can be found in templates/[profile].

Templates are based on default OpenAPI Generator templates.

Configuration files

Each target language has it's own configuration file located at config/[profile].yaml.

apiPackage: video.api.client.api.clients # API files output folder
modelPackage: folder.subfolder.subsubfolder # model output folder
files:
  page.mustache:
    folder: src/main/java/video/api/client/api/models
    destinationFilename: Page.java
  ApiVideoAuthInterceptor.mustache:
    folder: src/main/java/video/api/client/api/auth
    destinationFilename: ApiVideoAuthInterceptor.java
  EmptyArrayFixTypeAdapterFactory.mustache:
    folder: src/main/java/video/api/client/api
    destinationFilename: EmptyArrayFixTypeAdapterFactory.java
  UploadChunkRequestBody.mustache:
    folder: src/main/java/video/api/client/api/upload
    destinationFilename: UploadChunkRequestBody.java
  UploadProgressListener.mustache:
    folder: src/main/java/video/api/client/api/upload
    destinationFilename: UploadProgressListener.java
  ApiVideoClient.mustache:
    folder: src/main/java/video/api/client
    destinationFilename: ApiVideoClient.java
  pagination.md.mustache:
    folder: docs
    destinationFilename: Pagination.md
  post-generate.sh:
    destinationFilename: post-generate.sh

Generator sub-class

Some target language require tweaks that can't be done through the config file or the templates. In this case, a subclass of the generator is created at apivideo-generator/src/main/java/video/api/client/generator/[pascal-case-profile].java.

Development

We recommend the usage of a dedicated Java IDE to work on the development of this project. Especially if you want to tweak one of the language specific Codegen written in Java you'll need to navigate through the class hierarchy.

Configuration

A CodegenConfigurator instance is built from configurations coming from:

  • the CLI
  • a yml configuration file.

This CodegenConfigurator is then turned into a ClientOptInput (via the toClientOptInput method) to be fed to a Generator.

This is when our custom codegen, which implements CodegenConfig interface is involved.

The generation is actually done by the generate method of the DefaultGenerator class. This method will mainly :

  • processUserDefinedTemplates
  • generateModels given the list of files and available models
  • generateApis given the list of files and available operations
  • generateSupportingFiles given available models and operations

CLI

The profile configuration is first read from pom.xml, see java for example :

<profile>
    <id>java</id>
    <properties>
        <folder>java</folder>
        <generatorName>video.api.client.generator.Java</generatorName>
        <postGenerationScript>./post-generate.sh</postGenerationScript>
    </properties>
</profile>

When generating a client with the following command:

mvn package -P [profile]

Internally the generate command of the openapi-generator-cli run with the following options:

<configuration>
    <inputSpec>oas_apivideo.yaml</inputSpec>
    <generatorName>${generatorName}</generatorName>
    <templateDirectory>${project.basedir}/templates/${folder}</templateDirectory>
    <configurationFile>${project.basedir}/config/${folder}.yaml</configurationFile>
    <output>generated-clients/${folder}</output>
</configuration>

File

The yml config file -- is loaded in the CodegenConfigurator class via the fromFile method.

A class which manages the contextual configuration for code generation. This includes configuring the generator, templating, and the workflow which orchestrates these.

This helper also enables the deserialization of GeneratorSettings via application-specific Jackson JSON usage (see DynamicSettings.

Each entry under the files key of the yml configuration file is used to build a TemplateDefinition object. If not specified otherwise the file is treated as a SupportingFile.