[GitHub] [kafka] tombentley commented on a diff in pull request #12067: KAFKA-13780: Generate OpenAPI file for Connect REST API

[GitBox <gi...@apache.org>]

tombentley commented on code in PR #12067:
URL: https://github.com/apache/kafka/pull/12067#discussion_r892434763


##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/ConnectorsResource.java:
##########
@@ -257,11 +268,12 @@ public Response putConnectorConfig(final @PathParam("connector") String connecto
 
     @POST
     @Path("/{connector}/restart")
+    @Operation(summary = "Restart the specified connector")

Review Comment:
   Should we mention `includeTasks` and `onlyFailed` parameters?



##########
build.gradle:
##########
@@ -2522,6 +2525,26 @@ project(':connect:runtime') {
     standardOutput = new File(generatedDocsDir, "connect_metrics.html").newOutputStream()
   }
 
+  task setVersionInOpenAPISpec(type: Copy) {
+    from "$rootDir/gradle/openapi.template"
+    into "$buildDir/resources/docs"
+    rename ('openapi.template', 'openapi.yaml')
+    expand(kafkaVersion: "$rootProject.version")
+  }
+
+  task genConnectOpenAPIDocs(type: io.swagger.v3.plugins.gradle.tasks.ResolveTask, dependsOn: setVersionInOpenAPISpec) {

Review Comment:
   It also depends on having the connect runtime classes/jar.



##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/ConnectorsResource.java:
##########
@@ -285,23 +297,26 @@ public Response restartConnector(final @PathParam("connector") String connector,
 
     @PUT
     @Path("/{connector}/pause")
+    @Operation(summary = "Pause the specified connector")
     public Response pauseConnector(@PathParam("connector") String connector, final @Context HttpHeaders headers) {
         herder.pauseConnector(connector);
         return Response.accepted().build();
     }
 
     @PUT
     @Path("/{connector}/resume")
+    @Operation(summary = "Resume the specified connector")

Review Comment:
   Again, we should explain what happens if you resume a non-paused connector.



##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/ConnectorsResource.java:
##########
@@ -285,23 +297,26 @@ public Response restartConnector(final @PathParam("connector") String connector,
 
     @PUT
     @Path("/{connector}/pause")
+    @Operation(summary = "Pause the specified connector")

Review Comment:
   Mention the semantics of pausing an already paused connector.



##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/LoggingResource.java:
##########
@@ -59,6 +60,7 @@ public class LoggingResource {
      */
     @GET
     @Path("/")
+    @Operation(summary = "List the current loggers that have their levels explicitly set and their log levels")
     public Response listLoggers() {

Review Comment:
   The `Response` return types in this and other Resource classes means there are no `schemas` generated, which seems less than ideal.



##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/RootResource.java:
##########
@@ -36,6 +37,7 @@ public RootResource(Herder herder) {
 
     @GET
     @Path("/")
+    @Operation(summary = "Get details about the Connect cluster")

Review Comment:
   It's not just about the cluster, it's also info about this particular server.
   ```suggestion
       @Operation(summary = "Get details about this Connect worker and the id of the Kafka cluster it is connected to")
   ```



##########
connect/runtime/src/main/java/org/apache/kafka/connect/runtime/rest/resources/ConnectorPluginsResource.java:
##########
@@ -133,6 +135,7 @@ public ConfigInfos validateConfigs(
 
     @GET
     @Path("/")
+    @Operation(summary = "List all connector plugins installed")

Review Comment:
   We should explain the behaivour of the `connectorsOnly` parameter too



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: jira-unsubscribe@kafka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org