Skip to content
Permalink
Browse files
Autogenerate API docs for sidecar
Patch by Chris Lohfink, reviewed by Dinesh Joshi for CASSANDRA-15028
  • Loading branch information
clohfink committed Feb 22, 2019
1 parent a15ed26 commit 5712fb486b8e49b9b136d28fe2b9915e1d081689
Showing 3 changed files with 92 additions and 7 deletions.
@@ -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'
@@ -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
@@ -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;
}

0 comments on commit 5712fb4

Please sign in to comment.