Improve readability of the OpenAPI spec

* Fixed mismatched tags * Fixed minor issues with the schema Micronaut OpenAPI doesn't handle multipart/form-data params (`@Part`) :(
kestra-io · Jul 17, 2023 · 17d728d · 17d728d
1 parent 7507ada
commit 17d728d
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 26 deletions.
diff --git a/webserver/src/main/java/io/kestra/webserver/Application.java b/webserver/src/main/java/io/kestra/webserver/Application.java
@@ -12,13 +12,16 @@
         license = @License(name = "Apache 2.0", url = "https://raw.githubusercontent.com/kestra-io/kestra/master/LICENSE")
     ),
     tags = {
-        @Tag(name = "Flows", description = "Flows api"),
-        @Tag(name = "Templates", description = "Templates api"),
-        @Tag(name = "Executions", description = "Executions api"),
-        @Tag(name = "Logs", description = "Logs api"),
-        @Tag(name = "Plugins", description = "Plugins api"),
-        @Tag(name = "Stats", description = "Stats api"),
-        @Tag(name = "Misc", description = "Misc api"),
+        @Tag(name = "Flows", description = "Flows API"),
+        @Tag(name = "Templates", description = "Templates API"),
+        @Tag(name = "Executions", description = "Executions API"),
+        @Tag(name = "Logs", description = "Logs API"),
+        @Tag(name = "Plugins", description = "Plugins API"),
+        @Tag(name = "Stats", description = "Stats API"),
+        @Tag(name = "Misc", description = "Misc API"),
+        @Tag(name = "Blueprints", description = "Blueprints API"),
+        @Tag(name = "Blueprint Tags", description = "Blueprint Tags API"),
+        @Tag(name = "Metrics", description = "Metrics API"),
     }
 )
 public class Application {

diff --git a/webserver/src/main/java/io/kestra/webserver/controllers/BlueprintController.java b/webserver/src/main/java/io/kestra/webserver/controllers/BlueprintController.java
@@ -53,7 +53,7 @@ public PagedResults<BlueprintItem> blueprints(
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(value = "{id}/flow", produces = "application/yaml")
-    @Operation(tags = {"blueprints"}, summary = "Get a blueprint flow")
+    @Operation(tags = {"Blueprints"}, summary = "Get a blueprint flow")
     public String blueprintFlow(
         @Parameter(description = "The blueprint id") String id,
         HttpRequest<?> httpRequest
@@ -63,7 +63,7 @@ public String blueprintFlow(
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(value = "{id}/graph")
-    @Operation(tags = {"blueprints"}, summary = "Get a blueprint graph")
+    @Operation(tags = {"Blueprints"}, summary = "Get a blueprint graph")
     public Map<String, Object> blueprintGraph(
         @Parameter(description = "The blueprint id") String id,
         HttpRequest<?> httpRequest
@@ -73,7 +73,7 @@ public Map<String, Object> blueprintGraph(
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(value = "{id}")
-    @Operation(tags = {"blueprints"}, summary = "Get a blueprint")
+    @Operation(tags = {"Blueprints"}, summary = "Get a blueprint")
     public BlueprintItemWithFlow blueprint(
         @Parameter(description = "The blueprint id") String id,
         HttpRequest<?> httpRequest

diff --git a/webserver/src/main/java/io/kestra/webserver/controllers/ExecutionController.java b/webserver/src/main/java/io/kestra/webserver/controllers/ExecutionController.java
@@ -274,8 +274,8 @@ public HttpResponse<Void> delete(
     @Delete(uri = "executions/by-ids", produces = MediaType.TEXT_JSON)
     @ExecuteOn(TaskExecutors.IO)
     @Operation(tags = {"Executions"}, summary = "Delete a list of executions")
-    @ApiResponse(responseCode = "200", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
-    @ApiResponse(responseCode = "422", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
+    @ApiResponse(responseCode = "200", description = "On success", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
+    @ApiResponse(responseCode = "422", description = "Deleted with errors", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
     public MutableHttpResponse<?> deleteByIds(
         @Parameter(description = "The execution id") @Body List<String> executionsId
     ) {
@@ -609,8 +609,8 @@ public Execution restart(
     @ExecuteOn(TaskExecutors.IO)
     @Post(uri = "executions/restart/by-ids", produces = MediaType.TEXT_JSON)
     @Operation(tags = {"Executions"}, summary = "Restart a list of executions")
-    @ApiResponse(responseCode = "200", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
-    @ApiResponse(responseCode = "422", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
+    @ApiResponse(responseCode = "200", description = "On success", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
+    @ApiResponse(responseCode = "422", description = "Restarted with errors", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
     public MutableHttpResponse<?> restartByIds(
         @Parameter(description = "The execution id") @Body List<String> executionsId
     ) throws Exception {
@@ -815,8 +815,8 @@ public HttpResponse<?> resume(
     @ExecuteOn(TaskExecutors.IO)
     @Delete(uri = "executions/kill/by-ids", produces = MediaType.TEXT_JSON)
     @Operation(tags = {"Executions"}, summary = "Kill a list of executions")
-    @ApiResponse(responseCode = "200", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
-    @ApiResponse(responseCode = "422", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
+    @ApiResponse(responseCode = "200", description = "On success", content = {@Content(schema = @Schema(implementation = BulkResponse.class))})
+    @ApiResponse(responseCode = "422", description = "Killed with errors", content = {@Content(schema = @Schema(implementation = BulkErrorResponse.class))})
     public MutableHttpResponse<?> killByIds(
         @Parameter(description = "The execution id") @Body List<String> executionsId
     ) {

diff --git a/webserver/src/main/java/io/kestra/webserver/controllers/TemplateController.java b/webserver/src/main/java/io/kestra/webserver/controllers/TemplateController.java
@@ -48,7 +48,7 @@ public class TemplateController {
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(uri = "{namespace}/{id}", produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "Get a template")
+    @Operation(tags = {"Templates"}, summary = "Get a template")
     public Template index(
         @Parameter(description = "The template namespace") @PathVariable String namespace,
         @Parameter(description = "The template id") @PathVariable String id
@@ -60,7 +60,7 @@ public Template index(
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(uri = "/search", produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "Search for templates")
+    @Operation(tags = {"Templates"}, summary = "Search for templates")
     public PagedResults<Template> find(
         @Parameter(description = "The current page") @QueryValue(defaultValue = "1") int page,
         @Parameter(description = "The current page size") @QueryValue(defaultValue = "10") int size,
@@ -73,7 +73,7 @@ public PagedResults<Template> find(
 
     @ExecuteOn(TaskExecutors.IO)
     @Post(produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "Create a template")
+    @Operation(tags = {"Templates"}, summary = "Create a template")
     public HttpResponse<Template> create(
         @Parameter(description = "The template") @Valid @Body Template template
     ) throws ConstraintViolationException {
@@ -92,7 +92,7 @@ public HttpResponse<Template> create(
 
     @ExecuteOn(TaskExecutors.IO)
     @Put(uri = "{namespace}/{id}", produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "Update a template")
+    @Operation(tags = {"Templates"}, summary = "Update a template")
     public HttpResponse<Template> update(
         @Parameter(description = "The template namespace") @PathVariable String namespace,
         @Parameter(description = "The template id") @PathVariable String id,
@@ -109,7 +109,7 @@ public HttpResponse<Template> update(
 
     @ExecuteOn(TaskExecutors.IO)
     @Delete(uri = "{namespace}/{id}", produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "Delete a template")
+    @Operation(tags = {"Templates"}, summary = "Delete a template")
     @ApiResponse(responseCode = "204", description = "On success")
     public HttpResponse<Void> delete(
         @Parameter(description = "The template namespace") @PathVariable String namespace,
@@ -126,7 +126,7 @@ public HttpResponse<Void> delete(
 
     @ExecuteOn(TaskExecutors.IO)
     @Get(uri = "distinct-namespaces", produces = MediaType.TEXT_JSON)
-    @Operation(tags = {"Template"}, summary = "List all distinct namespaces")
+    @Operation(tags = {"Templates"}, summary = "List all distinct namespaces")
     public List<String> listDistinctNamespace() {
         return templateRepository.findDistinctNamespace();
     }
@@ -253,6 +253,7 @@ public List<ValidateConstraintViolation> validateTemplates(
     @ExecuteOn(TaskExecutors.IO)
     @Get(uri = "/export/by-query", produces = MediaType.APPLICATION_OCTET_STREAM)
     @Operation(
+        tags = {"Templates"},
         summary = "Export templates as a ZIP archive of yaml sources."
     )
     public HttpResponse<byte[]> exportByQuery(
@@ -267,6 +268,7 @@ public HttpResponse<byte[]> exportByQuery(
     @ExecuteOn(TaskExecutors.IO)
     @Post(uri = "/export/by-ids", produces = MediaType.APPLICATION_OCTET_STREAM, consumes = MediaType.APPLICATION_JSON)
     @Operation(
+        tags = {"Templates"},
         summary = "Export templates as a ZIP archive of yaml sources."
     )
     public HttpResponse<byte[]> exportByIds(
@@ -282,8 +284,8 @@ public HttpResponse<byte[]> exportByIds(
     @ExecuteOn(TaskExecutors.IO)
     @Delete(uri = "/delete/by-query")
     @Operation(
-        tags = {"Flows"},
-        summary = "Delete flows returned by the query parameters."
+        tags = {"Templates"},
+        summary = "Delete templates returned by the query parameters."
     )
     public HttpResponse<BulkResponse> deleteByQuery(
         @Parameter(description = "A string filter") @Nullable @QueryValue(value = "q") String query,
@@ -301,8 +303,8 @@ public HttpResponse<BulkResponse> deleteByQuery(
     @ExecuteOn(TaskExecutors.IO)
     @Delete(uri = "/delete/by-ids")
     @Operation(
-        tags = {"Flows"},
-        summary = "Delete flows by their IDs."
+        tags = {"Templates"},
+        summary = "Delete templates by their IDs."
     )
     public HttpResponse<BulkResponse> deleteByIds(
         @Parameter(description = "A list of tuple flow ID and namespace as flow identifiers") @Body List<IdWithNamespace> ids
@@ -335,6 +337,7 @@ private static byte[] zipTemplates(List<Template> templates) throws IOException
     @ExecuteOn(TaskExecutors.IO)
     @Post(uri = "/import", consumes = MediaType.MULTIPART_FORM_DATA)
     @Operation(
+        tags = {"Templates"},
         summary = "Import templates as a ZIP archive of yaml sources or a multi-objects YAML file."
     )
     @ApiResponse(responseCode = "204", description = "On success")