{"id":21334907,"url":"https://github.com/vlsergey/spring-data-rest-utils","last_synced_at":"2025-07-12T12:30:49.790Z","repository":{"id":46036640,"uuid":"370750537","full_name":"vlsergey/spring-data-rest-utils","owner":"vlsergey","description":"Gradle plug-in to generate OpenAPI specifications from Spring Data REST entities and repositories","archived":false,"fork":false,"pushed_at":"2023-11-20T22:02:17.000Z","size":314,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-13T03:14:53.380Z","etag":null,"topics":["gradle","gradle-plugin","hateoas","jpa-repositories","openapi","openapi-specification","spring-boot","spring-data","spring-data-rest"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vlsergey.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-25T15:57:56.000Z","updated_at":"2023-11-20T22:04:15.000Z","dependencies_parsed_at":"2022-09-08T23:51:10.520Z","dependency_job_id":null,"html_url":"https://github.com/vlsergey/spring-data-rest-utils","commit_stats":null,"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fspring-data-rest-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fspring-data-rest-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fspring-data-rest-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vlsergey%2Fspring-data-rest-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vlsergey","download_url":"https://codeload.github.com/vlsergey/spring-data-rest-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225820293,"owners_count":17529138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gradle","gradle-plugin","hateoas","jpa-repositories","openapi","openapi-specification","spring-boot","spring-data","spring-data-rest"],"created_at":"2024-11-21T23:36:14.352Z","updated_at":"2024-11-21T23:36:14.863Z","avatar_url":"https://github.com/vlsergey.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gradle plugin for Spring Data JPA REST and OpenAPI  \n\n[![Build with Gradle](https://github.com/vlsergey/spring-data-rest-utils/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/vlsergey/spring-data-rest-utils/actions/workflows/build.yml)\n[![Gradle Plugin](https://img.shields.io/maven-metadata/v?label=Gradle%20Plugin\u0026metadataUrl=https://plugins.gradle.org/m2/io/github/vlsergey/spring-data-rest-utils/io.github.vlsergey.spring-data-rest-utils.gradle.plugin/maven-metadata.xml)](https://plugins.gradle.org/plugin/io.github.vlsergey.spring-data-rest-utils)\n\nGenerates [OpenAPI specification](https://swagger.io/specification/) from JPA repositories exposed via [Spring Data REST](https://spring.io/projects/spring-data-rest) library.\n\n- [x] Generates schema components for both exposed and non-exposed classes\n- [x] Supports simple cases of inheritance with discriminators\n- [x] Exposes open projections and default projections\n- [X] Generates path and operations for supported commands\n  - Generates path items for CRUD methods: `findAll`, `findOneById`, `deleteById`, `save` (incl. PUT, POST and PATCH)\n  - Generates path items to fetch linked entities, create or delete associations\n  - Generates path items for query methods, available under `/search/` subpath\n\nExamples:\n- [Example of generated specification](https://github.com/vlsergey/spring-data-rest-utils/blob/master/src/test/resources/io/github/vlsergey/springdatarestutils/expected-example.yaml). [View in Swagger Editor Online](https://editor.swagger.io/?url=https://raw.githubusercontent.com/vlsergey/spring-data-rest-utils/master/src/test/resources/io/github/vlsergey/springdatarestutils/expected-example.yaml).\n- [Example package used for generation](https://github.com/vlsergey/spring-data-rest-utils/tree/master/src/test/java/io/github/vlsergey/springdatarestutils/example)\n\n## Enabling Gradle plugin\nUsing the plugins DSL:\n```groovy\nplugins {\n  id \"io.github.vlsergey.spring-data-rest-utils\" version \"0.45.1\"\n}\n```\n\nUsing [legacy plugin application](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application):\n```groovy\nbuildscript {\n  repositories {\n    maven {\n      url \"https://plugins.gradle.org/m2/\"\n    }\n  }\n  dependencies {\n    classpath \"io.github.vlsergey.springdatarestutils:spring-data-rest-utils:0.45.1\"\n  }\n}\n\napply plugin: \"io.github.vlsergey.spring-data-rest-utils\"\n```\n\nCurrently following tasks are supported:\n- `generateOpenAPIForSpringDataREST` -- generates [OpenAPI specification](https://swagger.io/specification/) from JPA repositories\n\n## Running\n`gradle generateOpenAPIForSpringDataREST`\n\n## Properties\n\nInclude the following snippet into `build.gradle`\n```groovy\nspringdatarestutils {\n    addXCustomAnnotations = ['org.tempuri.data.MyAnnotation'];\n    addXJavaClassName = true;\n    addXJavaComparable = true;\n    addXLinkedEntity = true;\n    basePackage = 'org.myname.myapp';\n    info.get().with {\n        title = 'MyApplication Data API';\n    }\n    servers.set([new io.swagger.v3.oas.models.servers.Server().url('/api/data')]);\n    output = file('../frontend/src/MyAppApi.yaml');\n    repositoryDetectionStrategy = 'ALL'\n}\n```\n\n### Main properties\n\n* `basePackage`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"\"`\n\nBase package to search JPA repository interfaces in.\n\n* `output`\u003cbr\u003e\ntype: `File`\u003cbr\u003e\ndefault: `\"api.yaml\"`\n\nWhere to output result. Supports both `.json` and `.yaml` extensions.\n\n* `repositoryDetectionStrategy`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"DEFAULT\"`\n\nThe 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`](https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest/core/mapping/RepositoryDetectionStrategy.RepositoryDetectionStrategies.html)\n\n### Specification Customization \n\n* `addXCustomAnnotations`\u003cbr\u003e\ntype: `List\u003cString\u003e`\u003cbr\u003e\ndefault: empty list\n\nInclude additional `x-annotation-simple-name` [extension](https://swagger.io/docs/specification/openapi-extensions/) 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`.\n\n* `addXJavaClassName`\u003cbr\u003e\ntype: `boolean`\u003cbr\u003e\ndefault: `false`\n\nInclude additional string `x-java-class-name` [extension](https://swagger.io/docs/specification/openapi-extensions/) to schemas to indicate source java class.\n\n* `addXJavaComparable`\u003cbr\u003e\ntype: `boolean`\u003cbr\u003e\ndefault: `false`\n\nInclude additional boolean `x-java-comparable` [extension](https://swagger.io/docs/specification/openapi-extensions/) to schemas to indicate if source java class implements `java.lang.Comparable` interface. Note, that `java.net.URL` does not implement it.\n\n* `addXLinkedEntity`\u003cbr\u003e\ntype: `boolean`\u003cbr\u003e\ndefault: `false`\n\nInclude additional `x-linked-entity` [extension](https://swagger.io/docs/specification/openapi-extensions/) to every `link` entry to indicate type of entity returned by corresponding `href` URL.\n\n* `info`\u003cbr\u003e\ntype: [`Info`](https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-models/src/main/java/io/swagger/v3/oas/models/info/Info.java)\n\nBean to be included as `info` part to OpenAPI spec. Plugin will try to fill some fields by default since some of them are required.\n\n* `servers`\u003cbr\u003e\ntype: `List\u003c`[`Server`](https://github.com/swagger-api/swagger-core/blob/master/modules/swagger-models/src/main/java/io/swagger/v3/oas/models/servers/Server.java)`\u003e`\u003cbr\u003e\ndefault: single server instance with `/api` url\n\nBeans to be included as `servers` part to OpenAPI spec.\n\n### Naming properies\n\n* `baseTypePrefix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"Base\"`\n\nPrefix to add to component's name that contains properties from root classes when inheritance is used.\n\n* `defaultTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"\"`\n\nSuffix to add to TypeScript interfaces to everything except enum classes and other special cases\n\n* `enumTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"\"`\n\nSuffix to add to TypeScript interfaces generated from enums\n\n* `linksTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"Links\"`\n\nSuffix to add to class names that contains the single `_links` field for each exposed class. Must be different from `defaultTypeSuffix`.\n\n* `linkTypeName`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"Link\"`\n\nHow to name TypeScript interface representing `org.springframework.hateoas.Link` data class.\n\n* `withLinksTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"WithLinks\"`\n\nSuffix 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.\n\n* `withProjectionsTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"WithLinks\"`\n\nPrefix to add to the name of composed schema with all projection of some entity.\n\n* `withProjectionsTypeSuffix`\u003cbr\u003e\ntype: `String`\u003cbr\u003e\ndefault: `\"WithLinks\"`\n\nSuffix to add to the name of composed schema with all projection of some entity.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlsergey%2Fspring-data-rest-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvlsergey%2Fspring-data-rest-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvlsergey%2Fspring-data-rest-utils/lists"}