Openapi generator for JeKa

A plugin to generate code from OpenAPI definitions.

This plugin is a lightweight wrapper for openapi-generator-cli and provides:

• Automatic installation: Installs the OpenAPI generator for the specified version.
• Easy access to common commands.
• Automatic setup of OpenAPI generation as a project source generator.

Resources:

• Command-line documentation: jeka openapi: --doc or jeka -cp=dev.jeka:openapi-plugin:0.11.8-1 openapi: --doc.
• Source code: Visit here.
• OpenAPI: Visit here.
• OpenAPI Generator: Visit here.
• OpenAPI Generator documentation: Visit here.

Configuration

You can append openapi source generator to your working project, just declaring properties in your jeka.properties file, following the below example:

# Import this plugin into JeKa classpath
jeka.classpath=dev.jeka:openapi-plugin:0.11.38-0

# By activating this plugin, project will automatically generate openapi code prior compilation.
@openapi=on

# Specifying the cli version is optional
@openapi.cliVersion=7.0.1

# Multiple generators can coexist in a single project by using different configuration keys.
# In this example, we use key="0".
@openapi.gen.config.0.inputSpec=https://petstore.swagger.io/v2/swagger.json
@openapi.gen.config.0.generatorName=spring
@openapi.gen.config.0.generationPackage=org.example.client
@openapi.gen.config.0.options.model-name-prefix=Rest
@openapi.gen.config.0.options.import-mappings=java.time.LocalDate=java.time.LocalDate
@openapi.gen.config.0.typeMappings.date=java.time.LocalDate
@openapi.gen.config.0.additionalProperties.useSpringBoot3=true

# Typical configuration to generate a client for Spring-Boot 3
# Needs to include 'org.openapitools:jackson-databind-nullable' dependency
@openapi.gen.config.1.inputSpec=https://api.foojay.io/swagger/foojay-discoapi-3.0.yml
@openapi.gen.config.1.generatorName=java
@openapi.gen.config.1.generationPackage=app.clients.generated
@openapi.gen.config.1.additionalProperties.library=resttemplate
@openapi.gen.config.1.additionalProperties.useJakartaEe=true
@openapi.gen.config.1.additionalProperties.useSpringBoot3=true

# It's also possible to specify the raw open-api command line.
@openapi.gen.cmdLine.my-client=generate -g java \
  --model-name-prefix Rest \
  --api-package org.example.client \
  --model-package org.example.client \
  -i https://petstore.swagger.io/v2/swagger.json \
  --library resttemplate \
  --additional-properties useJakartaEe=true

!!! Note: Intellij JeKa plugin provides auto-completion to suggest options and values.

See project example here.

Display openapi help

All available options can be listed using the provided methods:

Display openapi general help:

jeka openapi: helpCli

Display openapi 'generate' help:

jeka openapi: helpGenarate

Display list of available generators:

jeka openapi: helpListGenerators

Display options of a specific generator:

jeka openapi: helpGenerator helpGenerator=spring

Programmatic Usage

This is also possible to configure open-api generation programmatically.

String SPEC_URL = "https://petstore.swagger.io/v2/swagger.json";

// Create a source generator

JkOpenapiSourceGenerator openapiGen () {
    JkOpenapiSourceGenerator sourceGenerator = JkOpenapiSourceGenerator.of("spring", SPEC_URL);
    sourceGenerator.openapiCmd
            .addApiAndModelPackage("com.mycompany")
            .add(JkOpenapiCmdBuilder.MODEL_NAME_PREFIX, "Rest")
            .addAdditionalProperties("useSpringBoot3", "true")
            .add("--language-specific-primitives=Pet")
            .addImportMapping("Pet", "com.yourpackage.models.Pet")
            .addImportMapping("DateTime", "java.time.LocalDateTime")
            .addTypeMapping("DateTime", "java.time.LocalDateTime");
    return sourceGenerator;
}

@JkPostInit
private void postInit(ProjectKBean projectKBean) {
    JkProject project = projectKBean.project;
    project.compilation.addSourceGenerator(openapiGen());
}

See project example here.

---

Contributors

The plugin code lies in jeka-src and so is built using the base KBean instead of project.

How to release ?

Just use the github release mechanism. Creating a release consists in creating a tag, that will trigger a build and a publication on Maven Central.