[notablogger]

Summary

This release (4.0.0) adds a search endpoint and field-level control over the generated API:

• Search: POST /api/<path>/search. List Operation.SEARCH in expose. Clients send a JSON body of filters, for example {"price_gt": 10, "status_in": ["A","B"], "categoryId": 5}, and get back the matching records, paged when pageable = true. It works for JPA and MongoDB, on scalar fields, collections and JPA relations (filtered by id).
• @ExposeField(filterOperations = {...}) declares the filters a field accepts: EQ, NE, GT, GTE, LT, LTE, LIKE, IN, NOT_IN, IS_NULL. Mistakes are reported at compile time.
• @ExposeField(hidden = true) keeps a field out of the response and request DTOs.
• Fix: entities with a generic or array field (List<String>, Set<Integer>, byte[]) now generate DTOs.

⚠️ Breaking changes for 3.x users (major version 4.0.0):

• ignoredFields is removed from @ExposeEntity / @ExposeDocument. Mark each field instead:

  // 3.x
  @ExposeEntity(path = "users", ignoredFields = {"passwordHash"})
  // 4.0
  @ExposeField(hidden = true) private String passwordHash;

• The malformed-body 400 (urn:springxpose:malformed-body) now names the failing JSON property: detail says where the body is invalid, and a new errors map is keyed by that property ({"price": "Cannot deserialize value of type …"}). This applies to create, update and search bodies.

The sample is updated in notablogger/spring-xpose-sample-rest#2.

Type

• 🐛 Bug fix
• ✨ New feature / annotation attribute
• ♻️ Refactor (no behaviour change)
• 🧪 Tests only
• 📝 Documentation only
• 🔧 Build / CI change

Related issue

Related: #5 (superseded), #8, #9 (merged into this branch)

What was changed

• Annotations:

  • New Operation.SEARCH. It's opt-in: it is not one of the default expose operations.
  • New @ExposeField(filterOperations = ..., hidden = ...) and the FilterOperation enum.
  • ignoredFields is removed.

• The search endpoint:

  • @PostMapping("/search") with @RequestBody(required = false) <Entity>SearchRequest. An empty body ({}) or no body returns every record.
  • With pageable = true, page / size / sort are query parameters and the response is a Page. Without it, the response is a List.
  • It's a read. Security gives POST /api/<path>/search the read rule (readRoles / roles / authenticated() / permitAll()), while POST /api/<path> (create) keeps the write rule.

• Body keys: EQ uses the field name (price). Every other operation uses field_ plus the lower-cased operation name. Values are JSON: arrays for IN / NOT_IN, booleans for IS_NULL, ISO strings for dates. All keys are optional and combined with AND.

  Operation	Key	Java type	JPA	MongoDB
  EQ	price	field type	=	is
  NE	price_ne	field type	<> OR IS NULL	ne
  GT / GTE / LT / LTE	price_gt …	field type	> >= < <=	gt gte lt lte
  LIKE	name_like	String	lower(f) LIKE %v% (escaped)	regex(Pattern.quote(v), "i")
  IN	"status_in": ["A","B"]	List<T>	IN (…)	in
  NOT_IN	"status_not_in": ["A","B"]	List<T>	NOT IN (…) OR IS NULL	nin
  IS_NULL	"deletedAt_is_null": true	Boolean	IS NULL / IS NOT NULL	is(null) / ne(null)

• Unknown keys are rejected with 400, and the error lists the allowed keys. This covers typos, operations a field doesn't declare, and hidden fields. A @JsonAnySetter on the generated class enforces it, so the check holds whatever the application's Jackson setting for unknown properties is.

• Collection fields (@ElementCollection List<String> tags, Mongo arrays):

  • tags_in means "has any of".
  • tags_not_in means "has none of"; empty collections match.
  • tags_is_null matches null or empty.
  • JPA uses an EXISTS subquery, so rows aren't duplicated and paging totals stay correct.

• Relation filters:

  Relation	Keys	Operations	JPA
  @ManyToOne, owning @OneToOne	categoryId, categoryId_ne, categoryId_in, categoryId_not_in, categoryId_is_null	EQ, NE, IN, NOT_IN, IS_NULL	root.get("category").get("id"): the FK column, no join
  @OneToMany, @ManyToMany	suppliers_in, suppliers_not_in, suppliers_is_null	IN, NOT_IN, IS_NULL	EXISTS subquery on the related id

  The key's type is the related entity's @Id type, including one inherited from a @MappedSuperclass.

• hidden = true: leaves the field out of the response and request DTOs. Works on scalar fields, relations and Mongo fields; never on the @Id.

• Generated code:

  • <Entity>SearchRequest is the JSON body. Each property has @JsonProperty("price_gt") and @Schema(description = …).
  • <Entity>Spec builds a JPA Specification or a MongoDB Query.
  • JPA repositories of searchable entities also extend JpaSpecificationExecutor.

• OpenAPI:

  • The search body is one typed schema, with an example that lists every key with a type-correct placeholder, so it can be sent as is.
  • Pageable is documented as optional page / size / sort parameters (@ParameterObject when springdoc is present).

• Error responses: the malformed-body 400 has errors keyed by the JSON path, for example "price_gt", "categoryId_in[1]", or "pirce_gt": "Unknown search key …".

• Compile-time errors:

  • ranges on non-Comparable types; LIKE on a non-String; IS_NULL on primitives
  • scalar operations on collections; JPA collections without @ElementCollection; raw collections; arrays (except IS_NULL)
  • ranges or LIKE on relations; EQ / NE on to-many relations; the inverse side of a @OneToOne; related entities without a single @Id
  • hidden combined with filterOperations; two filters mapping to the same key

• Compile-time warnings:

  • filterOperations without SEARCH: the filters are unused.
  • SEARCH without any filterOperations: the endpoint returns every record.

• Bug fix: DtoGenerator / RequestDtoGenerator emit field types from the TypeMirror, so generic and array fields generate.

• Tests: 102 processor tests. FilterGeneratorTest covers search generation, security, warnings, the OpenAPI example, and Jackson reading the generated body.

• Docs:

  • annotation-reference.md has a new Search section. It covers keys, values, 400 errors, collections, relations, compile-time checks, limitations, and why search is a POST, including the plan to also serve it over HTTP QUERY (RFC 10008) once Spring supports it (Spring Framework 7.1, Add RFC 10008 (QUERY HTTP method) support spring-projects/spring-framework#34993).
  • Also updated: generated-artifacts.md, architecture.md, generator-guide.md, the README, and the comparison table.

How to test

1. Create a JPA entity with expose = {…, Operation.SEARCH} and these fields:
   • @ExposeField(filterOperations = {EQ, NE, LIKE}) String name
   • @ExposeField(filterOperations = {GT, LT}) BigDecimal price
   • @ExposeField(filterOperations = {IN, NOT_IN}) String status
   • @ExposeField(filterOperations = IS_NULL) Instant deletedAt
   • @ElementCollection @ExposeField(filterOperations = {IN, NOT_IN, IS_NULL}) List<String> tags
   • @ManyToOne @ExposeField(filterOperations = {EQ, NE, IN, NOT_IN, IS_NULL}) Category category
   • @ManyToMany @ExposeField(filterOperations = {IN, NOT_IN, IS_NULL}) Set<Supplier> suppliers
   • @ExposeField(hidden = true) String secret
2. Send POST /api/products/search with these bodies:
   • {"price_gt":10,"price_lt":100}, {"name_like":"widg"}, {"name_like":"50%"} (a literal %)
   • {"status_in":["A","B"]}, {"status_in":[]} (no filter), {"status_ne":"X"} (includes null)
   • {}, and no body at all (both return everything)
3. Send {"deletedAt_is_null":true}. Each of these should return 400 with errors keyed by the JSON key:
   • {"price_gt":"abc"}, {"deletedAt_is_null":"maybe"}, a non-ISO date
   • {"pirce_gt":1} and {"secret":"x"}; these errors also list the allowed keys
4. Send {"tags_in":["sale","new"]}, {"tags_not_in":["sale"]} and {"tags_is_null":true}.
5. Relation filters:
   • {"categoryId":1}: the SQL should be where category_id=?, with no join.
   • {"categoryId_ne":1}: includes uncategorised products.
   • {"suppliers_in":[1,2]} with ?size=2: each product once, correct totalElements.
6. Check that secret is absent from responses and from OpenAPI.
7. Security: with readRoles / writeRoles, a read-role user can search but not create.
8. In /v3/api-docs, /search has an optional body with the ProductSearchRequest schema and an example. Sending that example unchanged returns 200. page / size / sort are optional query params.

All of the above was run end to end against H2 (Spring Boot 4.0.6, springdoc 3.0.3), with this branch published to mavenLocal. MongoDB is covered by compile-tests only.

Generated output (if applicable)

Generated source (excerpt)

public final class ProductSearchRequest {
  @JsonProperty("price_gt")
  @Schema(description = "price greater than")
  private BigDecimal priceGt;

  @JsonProperty("tags_in")
  @Schema(description = "tags has any of")
  private List<String> tagsIn;

  public BigDecimal getPriceGt() { return priceGt; }
  public List<String> getTagsIn() { return tagsIn; }

  @JsonAnySetter
  void rejectUnknownKey(String key, Object value) {
    throw new IllegalArgumentException("Unknown search key '" + key + "' for Product — allowed keys: price_gt, tags_in");
  }
}

@PostMapping("/search")
public ResponseEntity<Page<ProductDto>> search(
    @RequestBody(required = false) ProductSearchRequest request, @ParameterObject Pageable pageable) {
  ProductSearchRequest filters = request != null ? request : new ProductSearchRequest();
  ...
  return ResponseEntity.ok(repository.findAll(ProductSpec.withFilters(filters), pageable).map(mapper::toDto));
}

// ProductSecurityConfigurer
.requestMatchers(HttpMethod.POST, "/api/products/search").hasAnyRole("CUSTOMER", "ADMIN")
.requestMatchers(HttpMethod.POST, "/api/products").hasAnyRole("ADMIN")

Checklist

• All existing tests pass (./gradlew :processor:test): 102/102 locally; ./gradlew build (including javadoc) is clean
• New tests added / updated to cover the change
• No MapStruct warnings in the sample project: feat(sample): demonstrate search, hidden fields and paging spring-xpose-sample-rest#2 (52/52 tests against this branch as 4.0.0)
• README.md updated if a public API / annotation attribute changed
• docs/tech/ updated if architecture or generated artifacts changed
• Commit messages follow type(scope): description format

🤖 Generated with Claude Code

https://claude.ai/code/session_01LcaFXaRgJhB2GBCbwnAc6V

[notablogger]

claude-review failure — not caused by this PR.

The check comes from .github/workflows/claude-code-review.yml, added to main by #4 and merged in here. In the run log Claude Code starts, then ends after 1 turn in ~2 s with total_cost_usd: 0 and empty modelUsage, reporting is_error: true — it never reached the model, so it reviewed nothing. That pattern points at authentication: the workflow uses secrets.CLAUDE_CODE_OAUTH_TOKEN, which is most likely missing or invalid (the action hides the exact message; show_full_output: true would show it).

No code change in this PR can fix it; it will fail the same way on every PR until the secret is set under Settings → Secrets and variables → Actions (e.g. via claude setup-token / /install-github-app). After that, a re-run of the job (or the next push) should go through. The repository's own checks (build, processor tests, branch name, PR title) are unaffected.

---

Generated by Claude Code