From 9e325b60faca054b976244a1fff8d4ef2595be41 Mon Sep 17 00:00:00 2001 From: Erik Merkle Date: Fri, 28 Jul 2023 10:43:41 -0500 Subject: [PATCH] Fix OpenAPI annotations for existing endpoints --- management-api-server/doc/openapi.json | 131 ++++++++++++++---- .../mgmtapi/resources/AuthResources.java | 8 +- .../resources/K8OperatorResources.java | 12 +- .../resources/KeyspaceOpsResources.java | 26 +++- .../mgmtapi/resources/TableOpsResources.java | 42 +++++- .../resources/v1/NodeOpsResources.java | 3 + 6 files changed, 185 insertions(+), 37 deletions(-) diff --git a/management-api-server/doc/openapi.json b/management-api-server/doc/openapi.json index 44680175..e53d632a 100644 --- a/management-api-server/doc/openapi.json +++ b/management-api-server/doc/openapi.json @@ -355,7 +355,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Role created" @@ -363,7 +366,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Username is empty" + "example" : "Username is empty", + "schema" : { + "type" : "string" + } } }, "description" : "Username and/or password is empty" @@ -422,7 +428,13 @@ "200" : { "content" : { "application/json" : { - "example" : [ "system_schema", "system", "system_auth", "system_distributed", "system_traces" ] + "example" : [ "system_schema", "system", "system_auth", "system_distributed", "system_traces" ], + "schema" : { + "type" : "array", + "items" : { + "type" : "string" + } + } } }, "description" : "List of Keyspaces" @@ -447,7 +459,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace Replication Settings altered successfully" @@ -455,7 +470,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Altering Keyspace failed. Non-empty 'keyspace_name' must be provided" + "example" : "Altering Keyspace failed. Non-empty 'keyspace_name' must be provided", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name or Replication Settings not provided" @@ -508,7 +526,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace created successfully" @@ -516,7 +537,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Keyspace creation failed. Non-empty 'keyspace_name' must be provided" + "example" : "Keyspace creation failed. Non-empty 'keyspace_name' must be provided", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name or Replication Settings not provided" @@ -545,7 +569,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "SSTables loaded successfully" @@ -553,7 +580,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Must provide a keyspace name" + "example" : "Must provide a keyspace name", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name or Table name not provided" @@ -580,6 +610,9 @@ "example" : { "class" : "org.apache.cassandra.locator.SimpleStrategy", "replication_factor" : "2" + }, + "schema" : { + "type" : "string" } } }, @@ -588,7 +621,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Get keyspace replication failed. Non-empty 'keyspaceName' must be provided" + "example" : "Get keyspace replication failed. Non-empty 'keyspaceName' must be provided", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name not provided" @@ -596,7 +632,10 @@ "404" : { "content" : { "text/plain" : { - "example" : "Get keyspace replication failed. Keyspace 'my_keyspace' does not exist." + "example" : "Get keyspace replication failed. Keyspace 'my_keyspace' does not exist.", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name not found" @@ -1177,7 +1216,10 @@ "200" : { "content" : { "application/json" : { - "example" : [ "table_1", "table_2" ] + "example" : [ "table_1", "table_2" ], + "schema" : { + "type" : "string" + } } }, "description" : "Table list" @@ -1185,7 +1227,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "List tables failed. Non-empty 'keyspaceName' must be provided" + "example" : "List tables failed. Non-empty 'keyspaceName' must be provided", + "schema" : { + "type" : "string" + } } }, "description" : "Keyspace name not provided" @@ -1210,7 +1255,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Table compaction successful" @@ -1218,7 +1266,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Invalid option combination: Can not use split-output here" + "example" : "Invalid option combination: Can not use split-output here", + "schema" : { + "type" : "string" + } } }, "description" : "Invalid table compaction request" @@ -1243,7 +1294,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Table creation successful" @@ -1251,7 +1305,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "Table creation failed: some failure message" + "example" : "Table creation failed: some failure message", + "schema" : { + "type" : "string" + } } }, "description" : "Table creation failed" @@ -1276,7 +1333,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Table flush successful" @@ -1308,7 +1368,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Table garbage collection successful" @@ -1316,7 +1379,10 @@ "400" : { "content" : { "text/plain" : { - "example" : "tombstoneOption must be either ROW or CELL" + "example" : "tombstoneOption must be either ROW or CELL", + "schema" : { + "type" : "string" + } } }, "description" : "Invalid table garbage collection request" @@ -1341,7 +1407,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Table scrub successful" @@ -1373,7 +1442,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "SSTable upgrade successful" @@ -1428,7 +1500,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Service is running" @@ -1444,7 +1519,10 @@ "200" : { "content" : { "text/plain" : { - "example" : "OK" + "example" : "OK", + "schema" : { + "type" : "string" + } } }, "description" : "Service is ready to handle requests" @@ -1554,7 +1632,10 @@ "200" : { "content" : { "application/json" : { - "example" : "{2207c2a9-f598-3971-986b-2926e09e239d: [10.244.1.4, 10.244.2.3, 10.244.3.3]}" + "example" : "{2207c2a9-f598-3971-986b-2926e09e239d: [10.244.1.4, 10.244.2.3, 10.244.3.3]}", + "schema" : { + "type" : "string" + } } }, "description" : "Gets the schema versions for each node. Useful for checking schema agreement" diff --git a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/AuthResources.java b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/AuthResources.java index cc9af6f2..5e598b95 100644 --- a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/AuthResources.java +++ b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/AuthResources.java @@ -12,6 +12,7 @@ import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import javax.ws.rs.POST; import javax.ws.rs.Path; @@ -38,13 +39,18 @@ public AuthResources(ManagementApplication application) { @ApiResponse( responseCode = "200", description = "Role created", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Username and/or password is empty", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject(value = "Username is empty"))) public Response createRole( @QueryParam(value = "username") String name, diff --git a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/K8OperatorResources.java b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/K8OperatorResources.java index 2a73257a..e4f25632 100644 --- a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/K8OperatorResources.java +++ b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/K8OperatorResources.java @@ -52,7 +52,11 @@ public K8OperatorResources(ManagementApplication application) { @ApiResponse( responseCode = "200", description = "Service is running", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) public Response checkLiveness() { return Response.ok("OK").build(); } @@ -66,7 +70,11 @@ public Response checkLiveness() { @ApiResponse( responseCode = "200", description = "Service is ready to handle requests", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse(responseCode = "500", description = "Service is not ready to handle requests") public Response checkReadiness() { return handle( diff --git a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/KeyspaceOpsResources.java b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/KeyspaceOpsResources.java index 6fffe174..c18e321c 100644 --- a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/KeyspaceOpsResources.java +++ b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/KeyspaceOpsResources.java @@ -15,6 +15,7 @@ import com.fasterxml.jackson.databind.ObjectMapper; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.ArraySchema; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.ExampleObject; import io.swagger.v3.oas.annotations.media.Schema; @@ -102,13 +103,18 @@ public Response cleanup(KeyspaceRequest keyspaceRequest) { @ApiResponse( responseCode = "200", description = "SSTables loaded successfully", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Keyspace name or Table name not provided", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject(value = "Must provide a keyspace name"))) @Operation( summary = "Load newly placed SSTables to the system without restart", @@ -143,13 +149,18 @@ public Response refresh( @ApiResponse( responseCode = "200", description = "Keyspace created successfully", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Keyspace name or Replication Settings not provided", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = @@ -190,13 +201,18 @@ public Response create(CreateOrAlterKeyspaceRequest createOrAlterKeyspaceRequest @ApiResponse( responseCode = "200", description = "Keyspace Replication Settings altered successfully", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Keyspace name or Replication Settings not provided", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = @@ -239,6 +255,7 @@ public Response alter(CreateOrAlterKeyspaceRequest createOrAlterKeyspaceRequest) content = @Content( mediaType = MediaType.APPLICATION_JSON, + array = @ArraySchema(schema = @Schema(implementation = String.class)), examples = @ExampleObject( value = @@ -275,6 +292,7 @@ public Response list(@QueryParam(value = "keyspaceName") String keyspaceName) { content = @Content( mediaType = MediaType.APPLICATION_JSON, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = @@ -285,6 +303,7 @@ public Response list(@QueryParam(value = "keyspaceName") String keyspaceName) { content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = @@ -295,6 +314,7 @@ public Response list(@QueryParam(value = "keyspaceName") String keyspaceName) { content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = diff --git a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/TableOpsResources.java b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/TableOpsResources.java index f0583be9..f48fd8b6 100644 --- a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/TableOpsResources.java +++ b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/TableOpsResources.java @@ -19,6 +19,7 @@ import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; import io.swagger.v3.oas.annotations.media.ExampleObject; +import io.swagger.v3.oas.annotations.media.Schema; import io.swagger.v3.oas.annotations.responses.ApiResponse; import java.util.ArrayList; import java.util.List; @@ -55,7 +56,11 @@ public TableOpsResources(ManagementApplication application) { @ApiResponse( responseCode = "200", description = "Table scrub successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @Operation(summary = "Scrub (rebuild sstables for) one or more tables", operationId = "scrub") public Response scrub(ScrubRequest scrubRequest) { return handle( @@ -93,7 +98,11 @@ public Response scrub(ScrubRequest scrubRequest) { @ApiResponse( responseCode = "200", description = "SSTable upgrade successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @Operation( summary = "Rewrite sstables (for the requested tables) that are not on the current version (thus upgrading them to said current version)", @@ -133,13 +142,18 @@ public Response upgradeSSTables( @ApiResponse( responseCode = "200", description = "Table compaction successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Invalid table compaction request", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = "Invalid option combination: Can not use split-output here"))) @@ -226,13 +240,18 @@ public Response compact(CompactRequest compactRequest) { @ApiResponse( responseCode = "200", description = "Table garbage collection successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Invalid table garbage collection request", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject(value = "tombstoneOption must be either ROW or CELL"))) @Operation( summary = "Remove deleted data from one or more tables", @@ -282,7 +301,11 @@ public Response garbageCollect( @ApiResponse( responseCode = "200", description = "Table flush successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @Operation(summary = "Flush one or more tables", operationId = "flush") public Response flush(KeyspaceRequest keyspaceRequest) { return handle( @@ -312,6 +335,7 @@ public Response flush(KeyspaceRequest keyspaceRequest) { content = @Content( mediaType = MediaType.APPLICATION_JSON, + schema = @Schema(implementation = String.class), examples = @ExampleObject(value = "[\n \"table_1\",\n \"table_2\"\n]"))) @ApiResponse( responseCode = "400", @@ -319,6 +343,7 @@ public Response flush(KeyspaceRequest keyspaceRequest) { content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject( value = "List tables failed. Non-empty 'keyspaceName' must be provided"))) @@ -349,13 +374,18 @@ public Response list( @ApiResponse( responseCode = "200", description = "Table creation successful", - content = @Content(mediaType = MediaType.TEXT_PLAIN, examples = @ExampleObject(value = "OK"))) + content = + @Content( + mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), + examples = @ExampleObject(value = "OK"))) @ApiResponse( responseCode = "400", description = "Table creation failed", content = @Content( mediaType = MediaType.TEXT_PLAIN, + schema = @Schema(implementation = String.class), examples = @ExampleObject(value = "Table creation failed: some failure message"))) @Consumes(MediaType.APPLICATION_JSON) @Operation(summary = "Create a new table in an existing keyspace", operationId = "createTable") diff --git a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/v1/NodeOpsResources.java b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/v1/NodeOpsResources.java index fba49996..56cdd558 100644 --- a/management-api-server/src/main/java/com/datastax/mgmtapi/resources/v1/NodeOpsResources.java +++ b/management-api-server/src/main/java/com/datastax/mgmtapi/resources/v1/NodeOpsResources.java @@ -99,6 +99,9 @@ public Response rebuild(@QueryParam("src_dc") String srcDatacenter) { content = @Content( mediaType = MediaType.APPLICATION_JSON, + // this should actually be a Response class object, but we don't have one. And a + // generic Map implementation here jsut results in a String typoe in the openAPI doc. + schema = @Schema(implementation = Map.class), examples = @ExampleObject( value =