rspec/rules/S6856/java/rule.adoc

== Why is this an issue?

The `@PathVariable` annotation in Spring extracts values from the URI path and binds them to method parameters in a Spring MVC controller.
It is commonly used with `@GetMapping`, `@PostMapping`, `@PutMapping`, and `@DeleteMapping` to capture path variables from the URI.
These annotations map HTTP requests to specific handler methods in a controller.
They are part of the Spring Web module and are commonly used to define the routes for different HTTP operations in a RESTful API.

If a method has a path template containing a placeholder, like "/api/resource/{id}", and there's no `@PathVariable` annotation on a method parameter to capture the id path variable, Spring will disregard the id variable.

This rule will raise an issue if a method has a path template with a placeholder, but no corresponding `@PathVariable`, or vice-versa.

== How to fix it

=== Code examples

==== Noncompliant code example

[source,java,diff-id=1,diff-type=noncompliant]
----
@GetMapping("/api/resource/{id}")
public ResponseEntity<String> getResourceById(Long id) { // Noncompliant - The 'id' parameter will not be automatically populated with the path variable value
  return ResponseEntity.ok("Fetching resource with ID: " + id);
}

@GetMapping("/api/asset/")
public ResponseEntity<String> getAssetById(@PathVariable Long id) { // Noncompliant - The 'id' parameter does not have a corresponding placeholder
  return ResponseEntity.ok("Fetching asset with ID: " + id);
}
----

==== Compliant solution

[source,java,diff-id=1,diff-type=compliant]
----
@GetMapping("/api/resource/{id}")
public ResponseEntity<String> getResourceById(@PathVariable Long id) { // Compliant
  return ResponseEntity.ok("Fetching resource with ID: " + id);
}

@GetMapping("/api/asset/{id}")
public ResponseEntity<String> getAssetById(@PathVariable Long id) {
  return ResponseEntity.ok("Fetching asset with ID: " + id);
}
----

== Resources

=== Documentation

* https://spring.io/guides/tutorials/rest/[Spring IO - Building REST services with Spring]
* https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/PathVariable.html[Spring Framework API - PathVariable]
* https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/GetMapping.html[Spring Framework API - GetMapping]
* https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/PostMapping.html[Spring Framework API - PostMapping]
* https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/PutMapping.html[Spring Framework API - PutMapping]
* https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/bind/annotation/DeleteMapping.html[Spring Framework API - DeleteMapping]

=== Articles & blog posts

* https://www.baeldung.com/spring-pathvariable[Baeldung - Spring @PathVariable]