RESTEasy integration with dynamically generated Swagger OpenAPI, Swag…

…ger UI and JAX-RS.

This patch introduces JAX-RS based annotation for defining APIs. It removes the manually
created api.yaml (OpenAPI spec) of the API definitions in favor of the dynamically
generated spec based on JAX-RS annotations. It also introduces Swagger UI to browse the
Sidecar APIs and to experiment with them. Finally, it updates the CircleCI workflows
such that the builds are run across both Docker and Machine images. We also gate packaging
builds on success of the compile and test builds. The rationale for running the builds
across both Docker and Machine images is that running the build on a Machine image exposed
a race condition.

Patch by Dinesh Joshi; Reviewed by Jon Haddad and Yifan Cai for CASSANDRASC-22

.circleci/config.yml

@@ -40,6 +40,21 @@ commands:
       - run: sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
 
 jobs:
+  java8_docker:
+    docker:
+     - image: circleci/openjdk:8-jdk-stretch
+    steps:
+     - checkout
+
+     - run: ./gradlew -i clean build --stacktrace
+
+     - store_artifacts:
+         path: build/reports
+         destination: test-reports
+
+     - store_test_results:
+         path: ~/repo/build/test-results/
+
   java8:
     <<: *base_job
 
@@ -53,7 +68,22 @@ jobs:
       - run: sudo update-java-alternatives -s adoptopenjdk-8-hotspot-amd64 && java -version
 
       # make sure it builds with build steps like swagger docs and dist
-      - run: ./gradlew build --stacktrace
+      - run: ./gradlew -i clean build --stacktrace
+
+      - store_artifacts:
+          path: build/reports
+          destination: test-reports
+
+      - store_test_results:
+          path: ~/repo/build/test-results/
+
+  java11_docker:
+    docker:
+      - image: circleci/openjdk:11-jdk-stretch
+    steps:
+      - checkout
+
+      - run: ./gradlew -i clean build --stacktrace
 
       - store_artifacts:
           path: build/reports
@@ -73,7 +103,7 @@ jobs:
 
       - run: sudo update-java-alternatives -s adoptopenjdk-11-hotspot-amd64 && java -version
 
-      - run: ./gradlew build --stacktrace
+      - run: ./gradlew -i clean build --stacktrace
 
       - store_artifacts:
           path: build/reports
@@ -84,13 +114,11 @@ jobs:
 
   # ensures we can build and install deb packages
   deb_build_install:
-    <<: *base_job
+    docker:
+      - image: circleci/openjdk:11-jdk-stretch
     steps:
       - checkout
-      - install_common
-      - install_java:
-          version: adoptopenjdk-11-hotspot
-      - run: ./gradlew buildDeb
+      - run: ./gradlew -i clean buildDeb
       - run: DEBIAN_FRONTEND=noninteractive sudo apt install -y ./build/distributions/cassandra-sidecar*.deb
       - run: test -f /opt/cassandra-sidecar/bin/cassandra-sidecar
 
@@ -100,40 +128,59 @@ jobs:
     steps:
       - checkout
       - run: yum install -y java-11-openjdk-devel  # the image uses root by default, no need for sudo
-      - run: JAVA_HOME=/usr/lib/jvm/java-11-openjdk ./gradlew buildRpm
+      - run: JAVA_HOME=/usr/lib/jvm/java-11-openjdk ./gradlew -i buildRpm
       - run: yum install -y ./build/distributions/cassandra-sidecar*.rpm
       - run: test -f /opt/cassandra-sidecar/bin/cassandra-sidecar
 
   docker_build:
     <<: *base_job
     steps:
       - checkout
-      - run: ./gradlew jibDockerBuild
+      - run: ./gradlew -i clean jibDockerBuild
 
   docs_build:
-    <<: *base_job
+    docker:
+      - image: circleci/openjdk:11-jdk-stretch
     steps:
       - checkout
-      - install_common
-      - install_java:
-          version: adoptopenjdk-11-hotspot
-      - run: ./gradlew build
+      - run: ./gradlew -i clean build --stacktrace
       - run: test -f build/docs/html5/user.html
 
 workflows:
   version: 2
-
-  test_java_8:
+  build-and-test:
     jobs:
       - java8
-
-  test_java_11:
-    jobs:
+      - java8_docker
       - java11
-
-  test_packaging:
-    jobs:
-      - deb_build_install
-      - rpm_build_install
-      - docker_build
-      - docs_build
+      - java11_docker
+      - docs_build:
+          requires:
+            - java8
+            - java8_docker
+            - java11
+            - java11_docker
+      - docker_build:
+          requires:
+            - java8
+            - java8_docker
+            - java11
+            - java11_docker
+      - rpm_build_install:
+          requires:
+            - java8
+            - java8_docker
+            - java11
+            - java11_docker
+      - deb_build_install:
+          requires:
+            - java8
+            - java8_docker
+            - java11
+            - java11_docker
+      - docker_build:
+          requires:
+            - java8
+            - java8_docker
+            - java11
+            - java11_docker

.gitignore

@@ -73,8 +73,6 @@ lib/jsr223/scala/*.jar
 
 /.ant-targets-build.xml
 
-# Generated files from the documentation
-src/main/resources/docs/*
 
 src/dist/*
 *.logdir_IS_UNDEFINED

build.gradle

@@ -15,6 +15,7 @@ plugins {
     id 'jacoco'
     id "com.github.spotbugs" version "3.0.0"
     id 'org.hidetake.swagger.generator' version '2.16.0'
+    id "io.swagger.core.v3.swagger-gradle-plugin" version "2.1.2"
 
     // https://github.com/nebula-plugins/gradle-ospackage-plugin/wiki
     id "nebula.ospackage" version "8.3.0"
@@ -83,20 +84,25 @@ dependencies {
     compile 'io.vertx:vertx-dropwizard-metrics:3.8.5'
     compile 'io.vertx:vertx-web-client:3.8.5'
 
+    compile 'io.swagger.core.v3:swagger-jaxrs2:2.1.0'
+    compile 'org.jboss.resteasy:resteasy-vertx:3.1.0.Final'
+    compile group: 'org.jboss.spec.javax.servlet', name: 'jboss-servlet-api_4.0_spec', version: '2.0.0.Final'
+
     // Trying to be exactly compatible with Cassandra's deps
     compile 'org.slf4j:slf4j-api:1.7.25'
     compile 'ch.qos.logback:logback-core:1.2.3'
     compile 'ch.qos.logback:logback-classic:1.2.3'
 
     compile 'com.datastax.cassandra:cassandra-driver-core:3.6+'
     compile group: 'com.google.inject', name: 'guice', version: '4.2.2'
+
     compile group: 'org.apache.commons', name: 'commons-configuration2', version: '2.7'
+    compile 'org.webjars:swagger-ui:3.10.0'
 
     runtime group: 'commons-beanutils', name: 'commons-beanutils', version: '1.9.3'
     runtime group: 'org.yaml', name: 'snakeyaml', version: '1.26'
 
     jolokia 'org.jolokia:jolokia-jvm:1.6.0:agent'
-    swaggerUI 'org.webjars:swagger-ui:3.10.0'
 
     testCompile group: 'org.cassandraunit', name: 'cassandra-unit-shaded', version: '3.3.0.2'
     testCompile 'com.datastax.cassandra:cassandra-driver-core:3.6.+:tests'
@@ -107,19 +113,6 @@ dependencies {
     integrationTestCompile group: 'com.datastax.oss.simulacron', name: 'simulacron-driver-3x', version: '0.8.10'
 }
 
-swaggerSources {
-    apidoc {
-        inputFile = file('api.yaml')
-        reDoc {
-            outputDir = file('src/main/resources/docs')
-            title = 'Cassandra Sidecar API Documentation'
-        }
-        ui {
-            outputDir = file('src/main/resources/docs/swagger')
-        }
-    }
-}
-
 task copyCodeStyle(type: Copy) {
     from "ide/idea/codeStyleSettings.xml"
     into ".idea"
@@ -222,6 +215,18 @@ applicationDistribution.from("LICENSE.txt") {
     into ""
 }
 
+// This task is defined by swagger-gradle-plugin
+// Resolves project openAPI specification and saves
+// the result in JSON during the build process.
+resolve {
+    outputFileName = 'api'
+    outputFormat = 'JSON'
+    prettyPrint = 'TRUE'
+    classpath = sourceSets.main.runtimeClasspath
+    resourcePackages = ['org.apache.cassandra.sidecar']
+    outputDir = file('build/generated/swagger')
+}
+
 // copyDist gets called on every build
 copyDist.dependsOn installDist, copyJolokia
 check.dependsOn checkstyleMain, checkstyleTest, integrationTest, jacocoTestReport