Updated Readme

teetangh · teetangh · commit a746ce183d56 · 2024-01-09T14:19:48.000+05:30
diff --git a/README.md b/README.md
@@ -1,59 +1,162 @@
-# Quickstart in Couchbase with Java and Spring Boot
-#### Build a REST API with Couchbase's Java SDK 3 and Spring Boot
+# Quickstart in Couchbase with Spring Boot and Java
 
-> This repo is designed to teach you how to connect to a Couchbase cluster to create, read, update, and delete documents and how to write simple parametrized N1QL queries.
+#### REST API using Couchbase Capella in Java using Spring Boot
 
-[![Try it now!](https://da-demo-images.s3.amazonaws.com/runItNow_outline.png?couchbase-example=java-springboot-quickstart-repo&source=github)](https://gitpod.io/#https://github.com/couchbase-examples/java-springboot-quickstart)
+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 Boot) 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.
+
+Full documentation for the tutorial can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-spring-boot-java/).
+
+If you are looking for a quick start using [Micronaut](https://micronaut.io/)](https://micronaut.io/), you can find it in this [repo](https://github.com/couchbase-examples/java-quickstart-micronaut).
 
-Full documentation can be found on the [Couchbase Developer Portal](https://developer.couchbase.com/tutorial-quickstart-java-springboot/).
 ## Prerequisites
+
 To run this prebuilt project, you will need:
 
-- Couchbase Server 7 Installed (version 7.0.0-5247 or higher)
-- Java SDK v1.8 or higher installed 
-- Code Editor installed (IntelliJ IDEA, Eclipse, or Visual Studio Code)
-- Maven command line
+- [Couchbase Capella](https://www.couchbase.com/products/capella/) cluster with [travel-sample](https://docs.couchbase.com/java-sdk/current/ref/travel-app-data-model.html) bucket loaded.
+  - To run this tutorial using a self-managed Couchbase cluster, please refer to the [appendix](#running-self-managed-couchbase-cluster).
+- [Java](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) 11 or higher installed
+  - 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)
 
-## Install Dependencies 
+## App Setup
 
+We will walk through the different steps required to get the application running.
 
-```sh
-mvn package
+### Cloning Repo
+
+```shell
+git clone https://github.com/couchbase-examples/java-springboot-quickstart
 ```
-> Note: Maven packages auto restore when building the project in IntelliJ IDEA or Eclipse depending on IDE configuration.
 
-### Database Server Configuration
+### Install Dependencies
+
+The dependencies for the application are specified in the `pom.xml` file in the source folder. Dependencies can be installed through `mvn` the default package manager for Java.
+
+```
+mvn clean install -DskipTests=true
+```
+
+Note: The `-DskipTests=true` option is used to skip the tests. The tests require the application to be running.
+
+Note: The application is tested with Java 17. If you are using a different version of Java, please update the `pom.xml` file accordingly.
+
+### Setup Database Configuration
 
-All configuration for communication with the database is stored in the `/src/main/resources/application.properties` file.  This includes the connection string, username, and password.  The default username is assumed to be `Administrator` and the default password is assumed to be `password`.  If these are different in your environment you will need to change them before running the application.
+To learn more about connecting to your Capella cluster, please follow the [instructions](https://docs.couchbase.com/cloud/get-started/connect.html).
 
-### Dependency Injection via DBSetupRunner class 
+Specifically, you need to do the following:
 
-The quickstart code provides a CommandLineRunner called DBSetupRunner in the runners folder that wires up the Bucket and Cluster objects for dependency injection.  This runner also creates the bucket, collection, scope, and indexes for the tutorial to run properly automatically when the application 
+- Create the [database credentials](https://docs.couchbase.com/cloud/clusters/manage-database-users.html) to access the travel-sample bucket (Read and Write) used in the application.
+- [Allow access](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) to the Cluster from the IP on which the application is running.
+
+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.
+
+```properties
+spring.couchbase.bootstrap-hosts=#######
+spring.couchbase.bucket.name=travel-sample
+spring.couchbase.bucket.user=#######
+spring.couchbase.bucket.password=#######
+spring.mvc.pathmatch.matching-strategy=ANT_PATH_MATCHER
+```
+
+Instead of the hash symbols, you need to add the values for the Couchbase connection.
+
+> Note: The connection string expects the `couchbases://` or `couchbase://` part.
 
 ## Running The Application
 
-At this point the application is ready and you can run it via your IDE or from the terminal:
+### Directly on Machine
+
+At this point, we have installed the dependencies, loaded the travel-sample data and configured the application with the credentials. The application is now ready and you can run it.
 
 ```sh
-mvn spring-boot:run -e -X
+mvn spring-boot:run
 ```
 
-You can launch your browser and go to the [Swagger start page](https://localhost:8080/swagger-ui/index.html).
+### Using Docker
 
-## Running The Tests
+Build the Docker image
 
-To run the standard integration tests (which requires a running Couchbase Server), use the following command:
+```sh
+docker build -t java-springboot-quickstart .
+```
+
+Run the Docker image
 
 ```sh
-mvn verify
+docker run -d --name springboot-container -p 8080:8080 java-springboot-quickstart
 ```
 
-## Project Setup Notes
+Note: The `application.properties` file has the connection information to connect to your Capella cluster. These will be part of the environment variables in the Docker container.
+
+### Verifying the Application
+
+Once the application starts, you can see the details of the application on the logs.
+
+![Application Startup](app_startup.png)
+
+The application will run on port 8080 of your local machine (http://localhost:8080). You will find the interactive Swagger documentation of the API if you go to the URL in your browser. Swagger documentation is used in this demo to showcase the different API endpoints and how they can be invoked. More details on the Swagger documentation can be found in the [appendix](#swagger-documentation).
+
+![Swagger Documentation](swagger_documentation.png)
+
+## Running Tests
+
+To run the integration tests, use the following commands:
+
+```sh
+mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.AirlineIntegrationTest
+mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.AirportIntegrationTest
+mvn test -Dtest=org.couchbase.quickstart.springboot.controllers.RouteIntegrationTest
+
+You can also run all the tests using the following command:
+mvn test
+```
+
+## Appendix
+
+### Data Model
+
+For this quickstart, we use three collections, `airport`, `airline` and `routes` that contain sample airports, airlines and airline routes respectively. The routes collection connects the airports and airlines as seen in the figure below. We use these connections in the quickstart to generate airports that are directly connected and airlines connecting to a destination airport. Note that these are just examples to highlight how you can use SQL++ queries to join the collections.
+
+![travel-sample data model](travel_sample_data_model.png)
+
+### Extending API by Adding New Entity
+
+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`. You'll have to implement the service interface `AirportServiceImpl.java`.
+- Define the repository in a new file in the `repositories` folder similar to the existing repositories like `AirportRepository.java`. You'll have to implement the repository interface `AirportRepositoryImpl.java`.
+- Add the new routes to the application in `Application.java`.
+
+### Running Self-Managed Couchbase Cluster
+
+If you are running this quickstart with a self-managed Couchbase cluster, you need to [load](https://docs.couchbase.com/server/current/manage/manage-settings/install-sample-buckets.html) the travel-sample data bucket in your cluster and generate the credentials for the bucket.
+
+You need to update the connection string and the credentials in the `application.properties` file in the `src/main/resources` folder.
+
+Note: Couchbase Server version 7 or higher must be installed and running before running the Spring Boot Java app.
+
+### Swagger Documentation
+
+Swagger documentation provides a clear view of the API including endpoints, HTTP methods, request parameters, and response objects.
+
+Click on an individual endpoint to expand it and see detailed information. This includes the endpoint's description, possible response status codes, and the request parameters it accepts.
+
+#### Trying Out the API
+
+You can try out an API by clicking on the "Try it out" button next to the endpoints.
 
-This project was based on the standard [Spring Boot project](https://spring.io/guides/gs/rest-service/).  The HealthCheckController is provided as a sanity check and is used in integration tests.  
+- Parameters: If an endpoint requires parameters, Swagger UI provides input boxes for you to fill in. This could include path parameters, query strings, headers, or the body of a POST/PUT request.
 
-A full list of packages are referenced in the pom.xml file
+- Execution: Once you've inputted all the necessary parameters, you can click the "Execute" button to make a live API call. Swagger UI will send the request to the API and display the response directly in the documentation. This includes the response code, response headers, and response body.
 
-## Conclusion
+#### Models
 
-Setting up a basic REST API in Spring Boot with Couchbase is fairly simple.  This project when run with Couchbase Server 7 installed creates a bucket in Couchbase, an index for our parameterized [N1QL query](https://docs.couchbase.com/java-sdk/current/howtos/n1ql-queries-with-sdk.html), and showcases basic CRUD operations needed in most applications.
+Swagger documents the structure of request and response bodies using models. These models define the expected data structure using JSON schema and are extremely helpful in understanding what data to send and expect.
