Skip to content

Codegen

About

Swagger Codgen is used to convert a Swagger specification (json/yml) in to an API client library or server stub. Codgen is written in Java and is easily customisable with and without editing the source.

Developing Codegen

The Codegen source is located on Github https://github.com/swagger-api/swagger-codegen

Editing Templates

Most of the time, you will only need to edit the Mustache files for your intended target (php client, Lumen server stub, etc).

These files are located in modules/swagger-codegen/src/main/resources/<output> Where output is your intended target (e.g. php-symfony).

All templates use the mustache file format. If you are not familiar with the syntax we suggest your read up on it. In their simplest form, the templates replace placeholders and allow you to include partials to generate source code.

Mustache5 Documentation

Editing Codegen Source

If you find that you need to extend Codegen, you can do this using a Java IDE. We would recommend IntelliJ Community Edition.

To get started, clone the github repository (or fork it) and open it up in your IDE.

Extending Templates

Most platforms/servers follow the same pattern but there is scope for customisation. You can edit the original files or add your own platform.

First, find your source Codegen class, all the classes are located in: modules/swagger-codegen/src/main/java/io/swagger/codegen/languages

We are going to look at the PHP Client. modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PhpClientCodegen.java

Around line 299 there is a series of calls to supportingFiles.

supportingFiles.add(new SupportingFile("ApiException.mustache", toPackagePath(invokerPackage, srcBasePath), "ApiException.php"));
        supportingFiles.add(new SupportingFile("Configuration.mustache", toPackagePath(invokerPackage, srcBasePath), "Configuration.php"));
        supportingFiles.add(new SupportingFile("ObjectSerializer.mustache", toPackagePath(invokerPackage, srcBasePath), "ObjectSerializer.php"));

These calls register individual files that are generated only once. If we wanted to add another file we would make another subsequent call with the same signature and parameters (but changing the mustache template and output PHP file)

Next, you need to add your new mustache file to the resource path mentioned earlier.

Building Codgen from Source

To generate the required jar files, we need to us Maven.

sudo dnf install -y maven
# Or
sudo yum install -y maven

To run the compilation process, navigate to the root of the repository.

For the inital build (run once), use mvn -N And follow subsequent builds with mvn install

Your output will be located in modules/swagger-codegen-cli/target