Gradle OpenApi Schema Codegen

This is a gradle plugin to generate Java code given an openapi 3.0.x or 3.1.0 specification. Unlike other codegen tools, this focuses mainly on the #/component/schema section. It generates immutable classes and a staged builder to support a safe way creating instances. The data classes support JSON conversions via jackson.

This plugin has three main advantages over using the standard OpenAPI Generator for schemas:

• Extended support of schema specifications: The generator can create classes for almost every possible schema definition
• Extended validation: The generated code can be validated automatically against every constraint one can define in the specification
• Improved compile-time safety: The generated classes do reflect more property attributes to improve the compile-time safety

The main features are:

• Immutable Java classes
• Staged builder pattern for compile-time-safe creation of instances
• JSON deserializing and serializing support with jackson
• Customization of the code generation
• Support for Java Bean Validation 2.x and Jakarta Bean Validation 2.x / 3.x
• Additional validation of object level constraints
• Extraction of description for enums
• Supports processing multiple specifications
• Support compositions (allOf, anyOf, oneOf)
• Customization of DTO classnames
• Easy integration with the official OpenAPI Generator

The implementation is based on the swagger-parser project.

Usage

Add the plugin section in your build.gradle:

plugins {
    id 'com.github.muehmar.openapischema' version '3.3.1'
}

and configure the generation:

openApiGenerator {
   schemas {
       apiV1 {
            inputSpec = "$projectDir/src/main/resources/openapi-v1.yml"
       }
   }
}

Documentation

1. Configuration
2. Supported OpenAPI versions
3. Warnings
4. Compositions
5. Nullability
6. Staged Builder
7. Validation
8. Extraction of enum-description
9. Parameters
10. Integration with OpenAPI Generator
11. Incremental Build
12. Limitations
13. Migration Guides
14. Change Log

Credits

• @eikek for the famous PList