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
- Generates path items for CRUD methods:
Examples:
- Example of generated specification. View in Swagger Editor Online.
- Example package used for generation
Using the plugins DSL:
plugins {
id "io.github.vlsergey.spring-data-rest-utils" version "${version}"
}
Using legacy plugin application:
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "io.github.vlsergey.springdatarestutils:spring-data-rest-utils:${version}"
}
}
apply plugin: "io.github.vlsergey.spring-data-rest-utils"
Currently following tasks are supported:
generateOpenAPIForSpringDataREST
-- generates OpenAPI specification from JPA repositories
gradle generateOpenAPIForSpringDataREST
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'
}
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
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.
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.