CASSSIDECAR-176: OpenAPI API description

CONTRIBUTING.md

@@ -37,6 +37,7 @@ We warmly welcome and appreciate contributions from the community.
   * [Future Composition](#future-composition)
   * [Failure Handling](#failure-handling)
   * [Cassandra Adapters](#cassandra-adapters)
+  * [REST APIs](#rest-apis)
 * [Source Code Style](#source-code-style)
 
 ## <a name="how-to-contribute"></a>How to Contribute
@@ -336,6 +337,21 @@ When adding shims, implement the minimum necessary changes in the new package an
 For example, if `base`'s minimum version is moved to 5.0, a Cassandra40 adapter package/subproject should be added, with a minimum version of 4.0.0.
 Within that project, the classes should all be named `Cassandra40*`, so `Cassandra40Adapter`, `Cassandra40Factory`, etc.
 
+### <a name="rest-apis"></a>REST APIs
+The project maintains an Open API documentation of all the provided REST APIs, located in `server/src/main/resources/openAPI`.
+When an API is modified or updated, this documentation needs to be maintained accordingly. For that, please take a look at the folder structure
+for the openAPI specification. The main file is called `sidecarApi.yaml`. There, all the endpoints are referenced. Let's take the health endpoint
+as an example:
+```yaml
+paths:
+  /__health:
+    $ref: paths/__health.yaml
+```
+
+That references the definition of the health endpoint, which can be found on the `paths` folder. On those references, we can find further references
+to their specific object schemas (which can be found under the `components/schemas` folder). For any common or shared parameters, please use
+the `components/parameters folder`.
+
 ## <a name="source-code-style"></a>Source Code Style
 
 The project provides an

server/build.gradle

@@ -30,6 +30,8 @@ plugins {
     id('maven-publish')
     // and produces a docker image
     id('com.google.cloud.tools.jib') version '3.4.4'
+    // openAPI
+    id "org.openapi.generator" version "7.11.0"
 }
 
 sourceCompatibility = JavaVersion.VERSION_11
@@ -254,3 +256,15 @@ checkstyleContainerTest.onlyIf { "true" != System.getenv("skipContainerTest") }
 spotbugsContainerTest.onlyIf { "true" != System.getenv("skipContainerTest") }
 
 check.dependsOn containerTest, integrationTest, jacocoTestReport
+
+// openAPI
+openApiValidate {
+    inputSpec.set("$rootDir/server/src/main/resources/openAPI/sidecarApi.yaml")
+    recommend.set(true)
+}
+openApiGenerate {
+    generatorName.set("html2")
+    inputSpec.set("$rootDir/server/src/main/resources/openAPI/sidecarApi.yaml")
+    outputDir.set("$buildDir/apiDocs")
+}
+compileJava.dependsOn tasks.openApiGenerate

server/src/main/resources/openAPI/components/parameters/cdcSegment.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: cdcSegment
+required: true
+schema:
+  type: string
+description: The id of a Cdc segment

server/src/main/resources/openAPI/components/parameters/component.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: component
+required: true
+schema:
+  type: string
+description: Component ID

server/src/main/resources/openAPI/components/parameters/index.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: index
+required: true
+schema:
+  type: string
+description: An index to retrieve components from

server/src/main/resources/openAPI/components/parameters/jobId.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: jobId
+required: true
+schema:
+  type: string
+description: Id of a job

server/src/main/resources/openAPI/components/parameters/keyspace.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+required: true
+name: keyspace
+schema:
+  type: string
+description: Keyspace name

server/src/main/resources/openAPI/components/parameters/snapshot.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: snapshot
+required: true
+schema:
+  type: string
+description: The snapshot ID

server/src/main/resources/openAPI/components/parameters/table.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: table
+required: true
+schema:
+  type: string
+description: Table name

server/src/main/resources/openAPI/components/parameters/uploadId.yaml

@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+in: path
+name: uploadId
+required: true
+schema:
+  type: string
+description: The id of a SSTable upload

server/src/main/resources/openAPI/components/schemas/cdcSegmentInfo.yaml

@@ -0,0 +1,40 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+type: object
+description: The information of a cdc segment
+properties:
+  name:
+    type: string
+    description: Cdc segment name
+    example: someName
+  size:
+    type: number
+    description: Cdc segment size
+    example: 1000
+  idx:
+    type: number
+    description: Cdc segment index
+    example: 1
+  completed:
+    type: boolean
+    description: Flag indicating if the segment has been completed
+    example: true
+  lastModifiedTimestamp:
+    type: number
+    description: When was the cdc segment last modified
+    example: 1234

server/src/main/resources/openAPI/components/schemas/cdcSegmentsResponse.yaml

@@ -0,0 +1,32 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+type: object
+description: The response for list cdc segments call
+properties:
+  host:
+    type: string
+    description: The host containing the segment
+    example: someName
+  port:
+    type: integer
+    description: The port of the host containing the segment
+    example: 80
+  segmentInfos:
+    type: array
+    items:
+      $ref: ./cdcSegmentInfo.yaml