add swagger docs to spring boot service

DataStax-Examples · Jun 15, 2020 · 04a0502 · 04a0502
1 parent 4a014a2
commit 04a0502
Show file tree

Hide file tree

Showing 8 changed files with 58 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -8,10 +8,10 @@ This repository contains sample inventory microservices to demonstrate how to us
 - [Frank Moley](https://github.com/fpmoles) - twitter handle [@fpmoles](https://twitter.com/fpmoles)
 
 #### Modules:
-- [`microservice-spring-boot`](microservice-spring-boot):
+- [`microservice-spring-boot`](microservice-spring-boot): Service for Products
    - **Persistence Layer** : uses Cassandra Java driver's `CqlSession` directly for queries to products table
    - **Exposition Layer** : uses `spring-web`  `@Controller`
-- [`microservice-spring-data`](microservice-spring-data): Service for Orders table
+- [`microservice-spring-data`](microservice-spring-data): Service for Orders
   - **Persistence Layer** : uses Spring Data Cassandra for data access to orders table
   - **Exposition Layer** : uses Spring Data Rest for API generation
 
@@ -69,8 +69,8 @@ kubectl -n cass-operator apply -f deploy/storage-class.yml
 # apply the operator manifest
 kubectl -n cass-operator apply -f https://raw.githubusercontent.com/DataStax-Academy/kubernetes-workshop-online/master/1-cassandra/11-install-cass-operator-v1.1.yaml
 
-# start a single C* 4.0 pod
-kubectl -n cass-operator apply -f deploy/cassandra-4.0.0-1node.yml 
+# start a single C* 4.0 node
+kubectl -n cass-operator apply -f deploy/cassandra-4.0.0-1node.yml
 ```
 
 Create the Kubernetes Secrets for database username and password
@@ -137,6 +137,8 @@ kubectl -n spring-data-service port-forward <spring-data-pod> 8081:8081
 ```
 
 #### Spring Boot service endpoints
+Explore the endpoints with Swagger: http://localhost:8083/swagger-ui.html
+
 Add products
 ```
 curl -X POST -H "Content-Type: application/json" -d '{"name": "mobile", "id":"123e4567-e89b-12d3-a456-556642440000", "description":"iPhone", "price":"500.00"}' http://localhost:8083/api/products/add
@@ -189,4 +191,4 @@ curl -X DELETE "http://localhost:8081/api/orders/delete/product-from-order?order
 Delete order with order_id = 123e4567-e89b-12d3-a456-556642440000
 ```
 curl -X DELETE "http://localhost:8081/api/orders/delete/order?orderId=123e4567-e89b-12d3-a456-556642440000"```
-```
+```
diff --git a/doc/pics/spring-k8s-cassandra-small.png b/doc/pics/spring-k8s-cassandra-small.png
diff --git a/doc/pics/swagger-spring-boot-service.png b/doc/pics/swagger-spring-boot-service.png
diff --git a/microservice-spring-boot/README.md b/microservice-spring-boot/README.md
@@ -51,6 +51,8 @@ kubectl -n spring-boot-service get pods
 kubectl -n spring-boot-service port-forward <pod-name> 8083:8083
 ```
 
+Explore the endpoints with Swagger: http://localhost:8083/swagger-ui.html
+
 Test the endpoints with curl
 
 Add products

diff --git a/microservice-spring-boot/pom.xml b/microservice-spring-boot/pom.xml
@@ -36,6 +36,18 @@
 			<groupId>com.datastax.oss</groupId>
 			<artifactId>java-driver-core</artifactId>
 		</dependency>
+
+		<!-- Swagger docs -->
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-swagger2</artifactId>
+			<version>2.9.2</version>
+		</dependency>
+		<dependency>
+			<groupId>io.springfox</groupId>
+			<artifactId>springfox-swagger-ui</artifactId>
+			<version>2.9.2</version>
+		</dependency>
 
 	</dependencies>
 

diff --git a/...pring-boot/src/main/java/com/datastax/examples/conf/SpringBootCassandraConfiguration.java b/...pring-boot/src/main/java/com/datastax/examples/conf/SpringBootCassandraConfiguration.java
@@ -12,6 +12,11 @@
 import java.net.InetSocketAddress;
 import java.nio.file.Paths;
 
+/* Configuration class for the Spring Boot microservice
+   Note: We could have used CassandraProperties here like we do in the Spring Data microservice.
+         Instead, we show a different technique of having application defined settings for the
+         database connection settings.
+*/
 @Configuration
 public class SpringBootCassandraConfiguration {
 
@@ -50,6 +55,9 @@ public String getLocalDataCenter() {
 
     @Bean
     public CqlSessionBuilderCustomizer sessionBuilderCustomizer() {
+        /* When using DataStax Astra, we must pass the secure connect bundle to the CqlSession
+           See documentation: https://docs.datastax.com/en/astra/aws/doc/dscloud/astra/dscloudUsingDrivers.html
+        */
         if (!astraSecureConnectBundle.equals("none")) {
             return builder -> builder
                     .withCloudSecureConnectBundle(Paths.get(this.astraSecureConnectBundle))
@@ -65,6 +73,9 @@ public CqlSessionBuilderCustomizer sessionBuilderCustomizer() {
 
     @Bean
     public DriverConfigLoaderBuilderCustomizer driverConfigLoaderBuilderCustomizer() {
+        /* When using DataStax Astra, we do not have to pass contact points like we normally would because
+           this metadata is contained in the secure connect bundle.
+         */
         if (!astraSecureConnectBundle.equals("none")) {
             return builder -> builder.without(DefaultDriverOption.CONTACT_POINTS);
         }

diff --git a/microservice-spring-boot/src/main/java/com/datastax/examples/conf/SwaggerConfig.java b/microservice-spring-boot/src/main/java/com/datastax/examples/conf/SwaggerConfig.java
@@ -0,0 +1,22 @@
+package com.datastax.examples.conf;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spring.web.plugins.Docket;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+@Configuration
+@EnableSwagger2
+public class SwaggerConfig {
+    @Bean
+    public Docket api() {
+        return new Docket(DocumentationType.SWAGGER_2)
+                .select()
+                .apis(RequestHandlerSelectors.any())
+                .paths(PathSelectors.any())
+                .build();
+    }
+}
diff --git a/microservice-spring-boot/src/main/java/com/datastax/examples/dao/ProductDao.java b/microservice-spring-boot/src/main/java/com/datastax/examples/dao/ProductDao.java
@@ -9,6 +9,10 @@
 import java.util.List;
 import java.util.UUID;
 
+/* Data Access Object for Products
+   Note: We could have optionally used the Object Mapper distributed with the Cassandra Java driver
+   See documentation: https://docs.datastax.com/en/developer/java-driver/latest/manual/mapper/
+ */
 public class ProductDao {
 
     private PreparedStatement insertProduct;