/gradle-openapi-schema

Generate schema sources for Java from an OpenAPI 3.0.x or 3.1.x specification.

Primary LanguageJavaMIT LicenseMIT

Build Status License: MIT

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