Swagger Codegen migration (swagger codegen generators repository)

Overview

Swagger v3 (also known as OpenAPI 3) is really different from the v2. For the specification have a look at: A Visual Guide to What's New in Swagger 3.0

This means that a lot of the generators needs to be rewritten.

In addition, some other technical and infrastructure changes were made. Some important points:

• the generators are now located in the swagger-codegen-generators repository instead of in the current swagger-codegen repository
• handlebars is used instead of mustache

This means that there is some migration work is required in order to be able to generate code using OpenAPI version 3 as input.

This pages contains information in order to help potential contributors.

Steps

Codegen classes

Create (or copy and paste) the Codegen classes from swagger-codegen from 3.0.0 branch to swagger-codegen-generators master branch. The new classes go in a subfolder of src/main/java.

The classes already read the OpenAPI 3 Specification and work with the corresponding classes (the swagger 2.0 classes have been already replaced)

New packages

In the swagger-codegen-generator project, a new structure was proposed. Instead of having everything in the io.swagger.codegen.languages package, package per languages should be created.

Example:

• Common classes: io.swagger.codegen.languages
• Classes for Java code generation: io.swagger.codegen.languages.java
• Classes for PHP code generation: io.swagger.codegen.languages.php

Template Version handling

A new member templateVersion was added in DefaultCodegenConfig. Of course there is also a getter: getTemplateVersion()

The processOpts() method needs to reads the value and to set the appropriate templateDir value accordinally. Example:

     @Override
     public void processOpts() {
         super.processOpts();
 
         String templateVersion = getTemplateVersion();
         if (StringUtils.isNotBlank(templateVersion)) {
             embeddedTemplateDir = templateDir = String.format("%s/JavaInflector", templateVersion);
         } else {
             embeddedTemplateDir = templateDir = String.format("%s/JavaInflector", DEFAULT_TEMPLATE_VERSION);
         }

Mustache Templates

Create code generator templates. Keep in mind that these templates now work with handlebars. The templates go in a subfolder of src/main/resources (in the v2 subfolder).

The existing templates (for Swagger v2) can be used as reference: in the swagger-codegen repository in the master branch (path: /modules/swagger-codegen/src/main/resources/)

The templates must be migrated: See the 'Swagger Codegen migration from Mustache and Handlebars templates.' page in the wiki.

Register the generators

Add your new class (full qualified name) in the service registry of the swagger-codegen-generator project (master branch). Path: /src/main/resources/META-INF/services/io.swagger.codegen.CodegenConfig

Cleanup work in the swagger-codegen repository

Add a @Deprecated mention on the old classes, and precise in the Javadoc where the new class is located.

/**
 * new version of this class can be found on: https://github.com/swagger-api/swagger-codegen-generators
 * @deprecated use <code>io.swagger.codegen.languages.java.JavaClientCodegen</code> instead.
 */
@Deprecated
public class JavaClientCodegen extends ...

Remove the old generators from the service registry of the swagger-codegen module. Path: /modules/swagger-codegen/src/main/resources/META-INF/services/io.swagger.codegen.CodegenConfig (3.0.0 branch).

Work in progress

• JaxRS => https://github.com/jmini/swagger-codegen-generators/tree/jaxrs branch @jmini fork, Discussion in Issue 7622.
• Php => Pull Request #14.