added oprtional parameters and examples, description + readme changes + api endpoints refactoring similar to python

Author: teetangh

README.md

@@ -5,7 +5,7 @@
 Often, the first step developers take after creating their database is to create a REST API that can perform Create, Read, Update, and Delete (CRUD) operations for that database. This repo is designed to teach you and give you a starter project (in Java using Spring Data) to generate such a REST API. After you have installed the travel-sample bucket in your database, you can run this application which is a REST API with Swagger documentation so that you can learn:
 
 1. How to create, read, update, and delete documents using Key-Value[ operations](https://docs.couchbase.com/java-sdk/current/howtos/kv-operations.html) (KV operations). KV operations are unique to Couchbase and provide super fast (think microseconds) queries.
-2. How to write simple parametrized [N1QL queries](https://docs.couchbase.com/java-sdk/current/howtos/n1ql-queries-with-sdk.html) using the built-in travel-sample bucket.
+2. How to write simple parametrized [SQL++ Queries](https://docs.couchbase.com/java-sdk/current/howtos/n1ql-queries-with-sdk.html) using the built-in travel-sample bucket.
 
 Full documentation for the tutorial can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-spring-data-java/).
 
@@ -17,11 +17,10 @@ To run this prebuilt project, you will need:
   - To run this tutorial using a self-managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).
 - [Java 17 or higher](https://www.oracle.com/java/technologies/javase-downloads.html)
   - Ensure that the Java version is compatible with the Couchbase SDK.
-- Loading Travel Sample Bucket
-  If travel-sample is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster:
-  - [Load travel-sample bucket in Couchbase Capella](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data)
-- Gradle
-  - You can install Gradle using the [instructions](https://gradle.org/install/).
+- [Loading Travel Sample Bucket](https://docs.couchbase.com/cloud/clusters/data-service/import-data-documents.html#import-sample-data)
+  - If `travel-sample` is not loaded in your Capella cluster, you can load it by following the instructions for your Capella Cluster
+- [Gradle 8.6 or higher](https://gradle.org/releases/)
+
 ## App Setup
 
 We will walk through the different steps required to get the application running.
@@ -55,22 +54,33 @@ Specifically, you need to do the following:
 
 All configuration for communication with the database is read from the environment variables. We have provided a convenience feature in this quickstart to read the environment variables from a local file, `application.properties` in the `src/main/resources` folder.
 
+You can also set the environment variables directly in your environment such as:
+
+```sh
+export DB_CONN_STR=couchbases://<cluster-url>
+export DB_USERNAME=Administrator
+export DB_PASSWORD=password
+```
+
+The `application.properties` file should look like this:
+
 ```properties
-server.use-forward-headers=true
 server.forward-headers-strategy=framework
 spring.couchbase.bootstrap-hosts=DB_CONN_STR
 spring.couchbase.bucket.name=travel-sample
 spring.couchbase.bucket.user=DB_USERNAME
 spring.couchbase.bucket.password=DB_PASSWORD
 spring.couchbase.scope.name=inventory
-spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
 ```
-Instead of DB_CONN_STR, DB_USERNAME, and DB_PASSWORD, you should replace these with the connection string, username, and password for your Couchbase cluster. The connection string is the URL of your cluster. For example, if you are using Capella, the connection string will look like `couchbases://cb.jnym5s9gv4ealbe.cloud.couchbase.com`. If you are using a local cluster, the connection string will be `localhost`.
 
-> Note: The connection string expects the `couchbases://` or `couchbase://` part.
+You can specify the connection string, username, and password using environment variables. The application will read these environment variables and use them to connect to the database.
+
+Additionally, you can specify the connection string, username, and password directly in the `application.properties` file.
 
+> Note: The connection string expects the `couchbases://` or `couchbase://` part.
 
 ## Cluster Connection Configuration
+
 Spring Data couchbase connector can be configured by providing a `@Configuration` [bean](https://docs.spring.io/spring-framework/docs/current/reference/html/core.html#beans-definition) that extends [`AbstractCouchbaseConfiguration`](https://docs.spring.io/spring-data/couchbase/docs/current/api/org/springframework/data/couchbase/config/AbstractCouchbaseConfiguration.html).
 
 ```java
@@ -144,7 +154,8 @@ public class CouchbaseConfiguration extends AbstractCouchbaseConfiguration {
 
 }
 ```
-> *from config/CouchbaseConfiguration.java*
+
+> _from config/CouchbaseConfiguration.java_
 
 This default configuration assumes that you have a locally running Couchbae server and uses standard administrative login and password for demonstration purpose.
 Applications deployed to production or staging environments should use less privileged credentials created using [Role-Based Access Control](https://docs.couchbase.com/go-sdk/current/concept-docs/rbac.html).
@@ -212,10 +223,11 @@ For this quickstart, we use three collections, `airport`, `airline` and `routes`
 
 If you would like to add another entity to the APIs, these are the steps to follow:
 
-- Create the new entity (collection) in the Couchbase bucket. You can create the collection using the [SDK](https://docs.couchbase.com/sdk-api/couchbase-java-client-3.5.2/com/couchbase/client/java/Collection.html#createScope-java.lang.String-) or via the [Couchbase Server interface](https://docs.couchbase.com/cloud/n1ql/n1ql-language-reference/createcollection.html).
-- Define the routes in a new file in the `controllers` folder similar to the existing routes like `AirportController.java`.
-- Define the service in a new file in the `services` folder similar to the existing services like `AirportService.java`. 
-- Define the repository in a new file in the `repositories` folder similar to the existing repositories like `AirportRepository.java`.
+- You can create the collection using the [SDK](https://docs.couchbase.com/sdk-api/couchbase-java-client-3.5.2/com/couchbase/client/java/Collection.html#createScope-java.lang.String-) or via the [Couchbase Server interface](https://docs.couchbase.com/cloud/n1ql/n1ql-language-reference/createcollection.html).
+- Create a new entity class in the `models` package similar to the existing entity classes like `Airport.java`.
+- Define the controller in a new file in the `controllers` folder similar to the existing classes like `AirportController.java`.
+- Define the service in a new file in the `services` folder similar to the existing classes like `AirportService.java`.
+- Define the repository in a new file in the `repositories` folder similar to the existing classes like `AirportRepository.java`.
 
 ### Running Self-Managed Couchbase Cluster
 

src/main/java/org/couchbase/quickstart/springdata/controller/AirlineController.java

@@ -2,8 +2,6 @@
 
 import java.util.Optional;
 
-import jakarta.validation.Valid;
-
 import org.couchbase.quickstart.springdata.models.Airline;
 import org.couchbase.quickstart.springdata.services.AirlineService;
 import org.springframework.dao.DataRetrievalFailureException;
@@ -25,6 +23,10 @@
 import com.couchbase.client.core.error.DocumentNotFoundException;
 
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import jakarta.validation.Valid;
 import lombok.extern.slf4j.Slf4j;
 
 @Slf4j
@@ -43,8 +45,14 @@ public AirlineController(AirlineService airlineService) {
     private static final String DOCUMENT_NOT_FOUND = "Document not found";
     private static final String DOCUMENT_ALREADY_EXISTS = "Document already exists";
 
-    @Operation(summary = "Get an airline by ID")
     @GetMapping("/{id}")
+    @Operation(summary = "Get an airline by ID", description = "Get Airline by specified ID.\n\nThis provides an example of using Key Value operations in Couchbase to retrieve a document with a specified ID. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `getAirline`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Airline found"),
+            @ApiResponse(responseCode = "404", description = "Airline not found"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "id", description = "Airline ID", required = true, example = "airline_10")
     public ResponseEntity<Airline> getAirline(@PathVariable String id) {
         try {
             Optional<Airline> airline = airlineService.getAirlineById(id);
@@ -59,8 +67,14 @@ public ResponseEntity<Airline> getAirline(@PathVariable String id) {
         }
     }
 
-    @Operation(summary = "Create an airline")
     @PostMapping("/{id}")
+    @Operation(summary = "Create an airline", description = "Create an airline with the specified ID.\n\nThis provides an example of using Key Value operations in Couchbase to create a document with a specified ID. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `createAirline`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "201", description = "Airline created"),
+            @ApiResponse(responseCode = "409", description = "Airline already exists"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "id", description = "Airline ID", required = true, example = "airline_10")
     public ResponseEntity<Airline> createAirline(@Valid @RequestBody Airline airline) {
         try {
             Airline newAirline = airlineService.createAirline(airline);
@@ -74,8 +88,14 @@ public ResponseEntity<Airline> createAirline(@Valid @RequestBody Airline airline
         }
     }
 
-    @Operation(summary = "Update an airline")
     @PutMapping("/{id}")
+    @Operation(summary = "Update an airline", description = "Update an airline with the specified ID.\n\nThis provides an example of using Key Value operations in Couchbase to update a document with a specified ID. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `updateAirline`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Airline updated"),
+            @ApiResponse(responseCode = "404", description = "Airline not found"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "id", description = "Airline ID", required = true, example = "airline_10")
     public ResponseEntity<Airline> updateAirline(@PathVariable String id, @Valid @RequestBody Airline airline) {
         try {
             Airline updatedAirline = airlineService.updateAirline(id, airline);
@@ -93,8 +113,14 @@ public ResponseEntity<Airline> updateAirline(@PathVariable String id, @Valid @Re
         }
     }
 
-    @Operation(summary = "Delete an airline")
     @DeleteMapping("/{id}")
+    @Operation(summary = "Delete an airline", description = "Delete an airline with the specified ID.\n\nThis provides an example of using Key Value operations in Couchbase to delete a document with a specified ID. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `deleteAirline`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "204", description = "Airline deleted"),
+            @ApiResponse(responseCode = "404", description = "Airline not found"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "id", description = "Airline ID", required = true, example = "airline_10")
     public ResponseEntity<Void> deleteAirline(@PathVariable String id) {
         try {
             airlineService.deleteAirline(id);
@@ -108,42 +134,42 @@ public ResponseEntity<Void> deleteAirline(@PathVariable String id) {
         }
     }
 
-    @Operation(summary = "List all airlines")
     @GetMapping("/list")
-    public ResponseEntity<Page<Airline>> listAirlines(@RequestParam(defaultValue = "0") int page,
-            @RequestParam(defaultValue = "10") int size) {
-        try {
-            Page<Airline> airlines = airlineService.getAllAirlines(PageRequest.of(page, size));
-            return new ResponseEntity<>(airlines, HttpStatus.OK);
-        } catch (Exception e) {
-            log.error(INTERNAL_SERVER_ERROR, e);
-            return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
-        }
-    }
-
-    @Operation(summary = "List all airlines by country")
-    @GetMapping("/country/{country}")
+    @Operation(summary = "List all airlines by country", description = "List all airlines by country.\n\nThis provides an example of using N1QL queries in Couchbase to retrieve documents with a specified field value. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `listAirlinesByCountry`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Airlines found"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "country", description = "Country", required = false, example = "United States")
     public ResponseEntity<Page<Airline>> listAirlinesByCountry(
-            @PathVariable String country,
+            @RequestParam(required = false) String country,
             @RequestParam(defaultValue = "0") int page,
             @RequestParam(defaultValue = "10") int size) {
         try {
-
-            Page<Airline> airlines = airlineService.findByCountry(country, PageRequest.of(page, size));
-            return new ResponseEntity<>(airlines, HttpStatus.OK);
+            if (country == null || country.isEmpty()) {
+                Page<Airline> airlines = airlineService.getAllAirlines(PageRequest.of(page, size));
+                return new ResponseEntity<>(airlines, HttpStatus.OK);
+            } else {
+                Page<Airline> airlines = airlineService.findByCountry(country, PageRequest.of(page, size));
+                return new ResponseEntity<>(airlines, HttpStatus.OK);
+            }
         } catch (Exception e) {
             log.error(INTERNAL_SERVER_ERROR, e);
             return new ResponseEntity<>(HttpStatus.INTERNAL_SERVER_ERROR);
         }
     }
 
-    @Operation(summary = "List all airlines by desination airport")
-    @GetMapping("/destination/{destinationAirport}")
+    @GetMapping("/to-airport")
+    @Operation(summary = "List all airlines by desination airport", description = "List all airlines by destination airport.\n\nThis provides an example of using N1QL queries in Couchbase to retrieve documents with a specified field value. \n\n Code: [`controllers/AirlineController.java`](https://github.com/couchbase-examples/java-springdata-quickstart/blob/main/src/main/java/org/couchbase/quickstart/springdata/controllers/AirlineController.java) \n File: `AirlineController.java` \n Method: `listAirlinesByDestinationAirport`", tags = {
+            "Airline" })
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Airlines found"),
+            @ApiResponse(responseCode = "500", description = "Internal server error") })
+    @Parameter(name = "destinationAirport", description = "Destination Airport", required = false, example = "SFO")
     public ResponseEntity<Page<Airline>> listAirlinesByDestinationAirport(
-            @PathVariable String destinationAirport,
+            @RequestParam(required = false) String destinationAirport,
             @RequestParam(defaultValue = "0") int page,
             @RequestParam(defaultValue = "10") int size) {
-
         try {
             Page<Airline> airlines = airlineService.findByDestinationAirport(destinationAirport,
                     PageRequest.of(page, size));