{"id":15489303,"url":"https://github.com/magrifle/search-api","last_synced_at":"2025-04-22T18:20:19.088Z","repository":{"id":42562697,"uuid":"144172938","full_name":"magrifle/search-api","owner":"magrifle","description":"A library that helps you instantly turn your spring API to a query engine","archived":false,"fork":false,"pushed_at":"2024-09-28T17:47:20.000Z","size":433,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-29T17:35:51.333Z","etag":null,"topics":["search-api","spring-boot","spring-data-jpa","spring-mvc"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magrifle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-09T15:41:04.000Z","updated_at":"2024-09-28T17:47:23.000Z","dependencies_parsed_at":"2025-03-04T04:30:41.446Z","dependency_job_id":"6d0ee2ec-ae41-4f89-b674-735aef600300","html_url":"https://github.com/magrifle/search-api","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magrifle%2Fsearch-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magrifle%2Fsearch-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magrifle%2Fsearch-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magrifle%2Fsearch-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magrifle","download_url":"https://codeload.github.com/magrifle/search-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250296451,"owners_count":21407037,"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":["search-api","spring-boot","spring-data-jpa","spring-mvc"],"created_at":"2024-10-02T07:04:55.463Z","updated_at":"2025-04-22T18:20:19.060Z","avatar_url":"https://github.com/magrifle.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# search-api\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n[![Build Status](https://app.travis-ci.com/magrifle/search-api.svg?branch=master)](https://app.travis-ci.com/github/magrifle/search-api)\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.magrifle/data-search-api.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.magrifle%22%20AND%20a:%22data-search-api%22)\n\nA library that helps you instantly turn your Spring powered endpoints into a query engine.\nIt makes use of `AOP` to intercept the calls to your `@Controller` or `@RestController` endpoint and then builds a `Specification` from the provided query parameters\n\n**Inspired by** [GitHub Search API](https://developer.github.com/v3/search/)\n\n| version | spring-data compatibility |\n|---|---|\n| 2.x \u003e | 2.x \u003e\n| \u003c2.x  | \u003c 2.x\n\n# What's new - 2.0.10?\n- Bug Fixes\n\n```java\n\n@Entity\n@DiscriminatorValue(\"CAR\")\npublic class CarEntity extends VehicleEntity\n{\n    private Integer numberOfDoors;\n}\n\n\n@Entity(name = \"vehicle_entity\")\n@Inheritance(strategy = InheritanceType.SINGLE_TABLE)\n@DiscriminatorColumn(name = \"vehicle_type\", discriminatorType = DiscriminatorType.STRING)\npublic class VehicleEntity\n{\n    @Id\n    @GeneratedValue(strategy = GenerationType.AUTO)\n    private Long id;\n\n    private Integer numberOfWheels;\n\n}\n\n//bean config\n...\nSearchKey numberOfDoors = new SearchKey(\"numberOfDoors\", \"vehicleEntity.numberOfDoors\");\nnumberOfDoors.setType(CarEntity.class);\nsearchKeys.add(numberOfDoors);\n``` \n\n[Full Change log](./CHANGELOG.md)\n\n# Example\n````curl\ncurl http://your.awesome.api/search?q=firstName:Jones,lastName:Fran*,dateCreated\u003e2018-01-01,age\u003c67,city:*ondon*\n````\n\n# Configuration\n\n1.  Add the dependency to the pom.xml file of your Spring boot or web MVC project. (Assume of course you're using maven package manager)\n\n````xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.github.magrifle\u003c/groupId\u003e\n  \u003cartifactId\u003edata-search-api\u003c/artifactId\u003e\n\u003c/dependency\u003e\n````\n\n2.  Next, you need to define a `@Bean` to enable the search API functionality\n\n````java\n@Configuration\npublic class ApiSearchConfig {\n    \n    @Bean\n    public DataSearchApi dataSearchApi() {\n        return new DataSearchApi();\n    }\n}\n\n````\n3) Next, we add a `@Bean` of type `SearchConfigurer` that holds the configuration of your data mapping.\nThis bean has a method `getSearchKeys()` that contains a list of all the `SearchKey` that are allowed in your search API.\n\nIt also contains some the configuration methods like `getDateKeyFormat()` that can be used to specify the allowed date format in the query string of the search API. \n\n```java\n@Configuration\npublic class ApiSearchConfig {\n\n    ...\n\n    @Bean\n    public SearchConfigurer\u003cItem\u003e getSearchKeysForItem() {\n        return new SearchConfigurer\u003cItem\u003e() {\n            @Override\n            public List\u003cSearchKey\u003e getSearchKeys() {\n                List\u003cSearchKey\u003e searchKeys = new ArrayList();\n                searchKeys.add(new SearchKey(\"name\"));\n                searchKeys.add(new SearchKey(\"pno\", \"passportNumber\"));\n                return searchKeys;\n            }\n        };\n    }\n}\n\n```\n\n4)  Finally, in your `@Controller` or `@RestController`, add the `@SearchApi` annotation\n\n````java\n\n@RestController\npublic class ApiController {\n\n    @Autowired\n    private ItemRepository itemRepository;\n    ...\n\n    @SearchApi(entity = Item.class)\n    @GetMapping(\"/search\")\n    public Page\u003cItem\u003e searchItems(SearchBuilder\u003cItem\u003e builder, Pageable pageable){\n        return itemRepository.findAll(builder.build(), pageable);\n    }\n}\n````\n**Note that your repository class must extend the `JpaSpecificationExecutor\u003cT\u003e` interface in `spring-data` to have access to the `findAll(Specification)` method.**\n\n\n# Parameters\n### `@SearchApi`\n\n| Name | Type | Description |\n|---|---|---|\n|`queryString`|`String`| `default \"q\"`. This is the query string parameter in the request that contains the search criteria. |\n|`keySeparator`|`char`| `default \",\"`. The character used to separate different criteria in the `queryString` |\n|`entity`|`class`| `required`. The entity class to be queried.|\n|`failOnMissingQueryString`|`boolean`| `default false`. If the `queryString` is empty, the endpoint would query the repository with an empty criteria which translates to `select * ...` in `sql`. You can turn off this behaviour by setting this parameter to `true` in which case a `SearchKeyValidationException` exception is thrown if the `queryString` is missing or does not contain any criteria. |\n|`caseSensitive`|`boolean`| `default true`. Determines if the library should do a strict/case-sensitive search or not |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagrifle%2Fsearch-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagrifle%2Fsearch-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagrifle%2Fsearch-api/lists"}