Autogenerate API docs for sidecar

Patch by Chris Lohfink, reviewed by Dinesh Joshi for CASSANDRA-15028

api.yaml

@@ -0,0 +1,57 @@
+openapi: 3.0.0
+
+info:
+  description: Apache Cassandra sidecar
+  version: "1.0.0"
+  title: Apache Cassandra Sidecar API
+  license:
+    name: Apache 2.0
+    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+
+tags:
+  - name: visibility
+    description: See status of Cassandra
+  - name: management
+    description: Execute, coordinate, or schedule operations
+
+paths:
+  /api/v1/__health:
+    get:
+      tags:
+        - visibility
+      summary: Check Cassandra Health
+      operationId: health
+      description: |
+        Lists status of Cassandra Daemon and its services
+      responses:
+        '200':
+          description: Current status if Cassandra is up and returning OK status
+          content:
+            application/json:
+              schema:
+                type: object
+                items:
+                  $ref: '#/components/schemas/HealthStatus'
+        '503':
+          description: Health check failed and returning NOT_OK
+          content:
+            application/json:
+              schema:
+                type: object
+                items:
+                  $ref: '#/components/schemas/HealthStatus'
+
+components:
+  schemas:
+    HealthStatus:
+      type: object
+      required:
+        - status
+      properties:
+        status:
+          type: string
+          enum:
+            - 'OK'
+            - 'NOT_OK'
+          description: if reads are able to run through binary interface. 'OK' or 'NOT_OK'
+          example: 'OK'

build.gradle

@@ -1,10 +1,13 @@
+plugins {
+    id 'java'
+    id 'application'
+    id 'idea'
+    id 'org.hidetake.swagger.generator' version '2.16.0'
+}
+
 group 'org.apache.cassandra'
 version '1.0-SNAPSHOT'
 
-apply plugin: 'java'
-apply plugin: 'application'
-apply plugin: 'idea'
-
 sourceCompatibility = 1.8
 
 repositories {
@@ -41,7 +44,7 @@ sourceSets {
     // This is needed as gradle considers `src/main/resources` as the default resources folder
     main {
         resources {
-            srcDirs = ['conf', 'setup']
+            srcDirs = ['conf', 'setup', 'src/main/resources']
         }
     }
     test {
@@ -70,7 +73,9 @@ dependencies {
 
     runtime group: 'commons-beanutils', name: 'commons-beanutils', version: '1.9.3'
     runtime group: 'org.yaml', name: 'snakeyaml', version: '1.23'
+
     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'
@@ -79,6 +84,19 @@ dependencies {
     testCompile group: 'io.vertx', name: 'vertx-junit5', version: '3.6.3'
 }
 
+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"
@@ -104,6 +122,8 @@ clean {
     delete "$projectDir/lib"
     println "Deleting agents $projectDir/src/dist/agents"
     delete "$projectDir/src/dist/agents"
+    println "Deleting generated docs $projectDir/src/main/resources/docs"
+    delete "$projectDir/src/main/resources/docs"
 
 }
 
@@ -113,5 +133,4 @@ test {
 
 // copyDist gets called on every build
 copyDist.dependsOn installDist
-build.dependsOn copyDist
-build.dependsOn copyJolokia
+build.dependsOn copyDist, generateReDoc, generateSwaggerUI, copyJolokia

src/main/java/org/apache/cassandra/sidecar/MainModule.java

@@ -28,6 +28,7 @@
 import io.vertx.ext.dropwizard.DropwizardMetricsOptions;
 import io.vertx.ext.web.Router;
 import io.vertx.ext.web.handler.LoggerHandler;
+import io.vertx.ext.web.handler.StaticHandler;
 import org.apache.cassandra.sidecar.routes.HealthCheck;
 import org.apache.cassandra.sidecar.routes.HealthService;
 import org.apache.commons.configuration2.YAMLConfiguration;
@@ -81,6 +82,14 @@ public Router vertxRouter(Vertx vertx, HealthService healthService)
     {
         Router router = Router.router(vertx);
         router.route().handler(LoggerHandler.create());
+
+        // include docs generated into src/main/resources/docs
+        StaticHandler swagger = StaticHandler.create()
+                                             .setWebRoot("docs")
+                                             .setCachingEnabled(false);
+        router.route().path("/docs/*").handler(swagger);
+
+        // API paths
         router.route().path("/api/v1/__health").handler(healthService::handleHealth);
         return router;
     }