Gradle plugin for Spring Data JPA REST and OpenAPI

Generates OpenAPI specification from JPA repositories exposed via Spring Data REST library.

• Generates schema components for both exposed and non-exposed classes
• Supports simple cases of inheritance with discriminators
• Exposes open projections and default projections
• Generates path and operations for supported commands
  • Generates path items for CRUD methods: findAll, findOneById, deleteById, save (incl. PUT, POST and PATCH)
  • Generates path items to fetch linked entities, create or delete associations
  • Generates path items for query methods, available under /search/ subpath

Examples:

• Example of generated specification. View in Swagger Editor Online.
• Example package used for generation

Enabling Gradle plugin

Using the plugins DSL:

plugins {
  id "io.github.vlsergey.spring-data-rest-utils" version "0.45.1"
}

Using legacy plugin application:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "io.github.vlsergey.springdatarestutils:spring-data-rest-utils:0.45.1"
  }
}

apply plugin: "io.github.vlsergey.spring-data-rest-utils"

Currently following tasks are supported:

• generateOpenAPIForSpringDataREST -- generates OpenAPI specification from JPA repositories

Running

gradle generateOpenAPIForSpringDataREST

Properties

Include the following snippet into build.gradle

springdatarestutils {
    addXCustomAnnotations = ['org.tempuri.data.MyAnnotation'];
    addXJavaClassName = true;
    addXJavaComparable = true;
    addXLinkedEntity = true;
    basePackage = 'org.myname.myapp';
    info.get().with {
        title = 'MyApplication Data API';
    }
    servers.set([new io.swagger.v3.oas.models.servers.Server().url('/api/data')]);
    output = file('../frontend/src/MyAppApi.yaml');
    repositoryDetectionStrategy = 'ALL'
}

Main properties

• basePackage
  type: String
  default: ""

Base package to search JPA repository interfaces in.

• output
  type: File
  default: "api.yaml"

Where to output result. Supports both .json and .yaml extensions.

• repositoryDetectionStrategy
  type: String
  default: "DEFAULT"

The strategy to determine whether a given repository is to be exported by Spring Data REST. Values (and actual implementation) are reused from Spring Data REST RepositoryDetectionStrategies

Specification Customization

• addXCustomAnnotations
  type: List<String>
  default: empty list

Include additional x-annotation-simple-name extension to property when field (read method) is annotated with annotation of such classes. Can be used for custom validation or UI improvements like provising @Multiline to generate textarea instead of input.

• addXJavaClassName
  type: boolean
  default: false

Include additional string x-java-class-name extension to schemas to indicate source java class.

• addXJavaComparable
  type: boolean
  default: false

Include additional boolean x-java-comparable extension to schemas to indicate if source java class implements java.lang.Comparable interface. Note, that java.net.URL does not implement it.

• addXLinkedEntity
  type: boolean
  default: false

Include additional x-linked-entity extension to every link entry to indicate type of entity returned by corresponding href URL.

• info
  type: Info

Bean to be included as info part to OpenAPI spec. Plugin will try to fill some fields by default since some of them are required.

• servers
  type: List<Server>
  default: single server instance with /api url

Beans to be included as servers part to OpenAPI spec.

Naming properies

• baseTypePrefix
  type: String
  default: "Base"

Prefix to add to component's name that contains properties from root classes when inheritance is used.

• defaultTypeSuffix
  type: String
  default: ""

Suffix to add to TypeScript interfaces to everything except enum classes and other special cases

• enumTypeSuffix
  type: String
  default: ""

Suffix to add to TypeScript interfaces generated from enums

• linksTypeSuffix
  type: String
  default: "Links"

Suffix to add to class names that contains the single _links field for each exposed class. Must be different from defaultTypeSuffix.

• linkTypeName
  type: String
  default: "Link"

How to name TypeScript interface representing org.springframework.hateoas.Link data class.

• withLinksTypeSuffix
  type: String
  default: "WithLinks"

Suffix to add to interface names that contains both _links field and all other properties for exposed class. Such types are usual result of findOne() operation.

• withProjectionsTypeSuffix
  type: String
  default: "WithLinks"

Prefix to add to the name of composed schema with all projection of some entity.

• withProjectionsTypeSuffix
  type: String
  default: "WithLinks"

Suffix to add to the name of composed schema with all projection of some entity.