From d63cc9e37a8bf5eaefcdd5ebe318d45918f50bbf Mon Sep 17 00:00:00 2001
From: Francois Prunayre <fx.prunayre@gmail.com>
Date: Tue, 14 Jan 2025 15:41:21 +0100
Subject: [PATCH] API / Improve OpenAPI spec schema.

* /site response is using SettingsListToObjectSerializer which returns a simple object
* OpenAPI generator does not generate parameters for process API.
---
 .../org/fao/geonet/api/OpenApiConfig.java     |  2 ++
 .../api/records/MetadataProcessApi.java       | 14 ++++++++++++-
 .../java/org/fao/geonet/api/site/SiteApi.java | 20 ++++++++++++++++++-
 3 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/services/src/main/java/org/fao/geonet/api/OpenApiConfig.java b/services/src/main/java/org/fao/geonet/api/OpenApiConfig.java
index feed405074f..0e7b5660f60 100644
--- a/services/src/main/java/org/fao/geonet/api/OpenApiConfig.java
+++ b/services/src/main/java/org/fao/geonet/api/OpenApiConfig.java
@@ -26,11 +26,13 @@
 package org.fao.geonet.api;
 
 import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.ExternalDocumentation;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Contact;
 import io.swagger.v3.oas.models.info.Info;
 import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.media.Schema;
 import io.swagger.v3.oas.models.servers.Server;
 import io.swagger.v3.oas.models.servers.ServerVariable;
 import io.swagger.v3.oas.models.servers.ServerVariables;
diff --git a/services/src/main/java/org/fao/geonet/api/records/MetadataProcessApi.java b/services/src/main/java/org/fao/geonet/api/records/MetadataProcessApi.java
index 2392c7fc2ae..bd156b2d581 100644
--- a/services/src/main/java/org/fao/geonet/api/records/MetadataProcessApi.java
+++ b/services/src/main/java/org/fao/geonet/api/records/MetadataProcessApi.java
@@ -24,6 +24,10 @@
 package org.fao.geonet.api.records;
 
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.enums.Explode;
+import io.swagger.v3.oas.annotations.enums.ParameterIn;
+import io.swagger.v3.oas.annotations.enums.ParameterStyle;
+import io.swagger.v3.oas.annotations.media.Schema;
 import io.swagger.v3.oas.annotations.responses.ApiResponse;
 import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -167,7 +171,15 @@ ResponseEntity<Element> processRecordPreview(
     public @ResponseBody
     ResponseEntity processRecord(
         @Parameter(description = API_PARAM_RECORD_UUID, required = true) @PathVariable String metadataUuid,
-        @Parameter(description = ApiParams.API_PARAM_PROCESS_ID) @PathVariable String process, HttpServletRequest request)
+        @Parameter(description = ApiParams.API_PARAM_PROCESS_ID, example = "thumbnail-add") @PathVariable String process,
+        @Parameter(name = "processParams", description = "Parameters to pass to the process",
+            in = ParameterIn.QUERY,
+            required = false,
+            schema = @Schema(type = "object", additionalProperties = Schema.AdditionalPropertiesValue.TRUE, example = "{\"thumbnail_url\":\"http://\",\"thumbnail_desc\":\"Dataset overview\"}"),
+            style = ParameterStyle.FORM,
+            explode = Explode.TRUE)
+        @RequestParam(required = false) Map<String,String> processParams,
+        HttpServletRequest request)
         throws Exception {
         AbstractMetadata metadata = ApiUtils.canEditRecord(metadataUuid, request);
         boolean save = true;
diff --git a/services/src/main/java/org/fao/geonet/api/site/SiteApi.java b/services/src/main/java/org/fao/geonet/api/site/SiteApi.java
index 2345806d934..cc38e7f4eff 100644
--- a/services/src/main/java/org/fao/geonet/api/site/SiteApi.java
+++ b/services/src/main/java/org/fao/geonet/api/site/SiteApi.java
@@ -179,11 +179,29 @@ public static void reloadServices(ServiceContext context) throws Exception {
         summary = "Get site (or portal) description",
         description = "")
     @RequestMapping(
+        consumes = {MediaType.APPLICATION_JSON_VALUE, MediaType.ALL_VALUE},
         produces = MediaType.APPLICATION_JSON_VALUE,
         method = RequestMethod.GET)
     @ResponseStatus(HttpStatus.OK)
     @ApiResponses(value = {
-        @ApiResponse(responseCode = "200", description = "Site description.")
+        @ApiResponse(responseCode = "200", description = "Site description.",
+        content = {
+            @Content(schema = @Schema(
+                type = "object",
+                additionalPropertiesSchema = String.class
+            ),
+                examples = @ExampleObject(value = "{\n" +
+                "  \"system/site/name\": \"My GeoNetwork catalogue\",\n" +
+                "  \"system/site/organization\": \"My organization\",\n" +
+                "  \"system/site/siteId\": \"33bc8c82-7ac2-49b6-a22b-af7376dbcf10\",\n" +
+                "  \"system/platform/version\": \"4.4.7\",\n" +
+                "  \"system/platform/subVersion\": \"SNAPSHOT\",\n" +
+                "  \"node/default\": \"true\",\n" +
+                "  \"node/id\": \"33bc8c82-7ac2-49b6-a22b-af7376dbcf10\",\n" +
+                "  \"node/name\": \"My GeoNetwork catalogue\",\n" +
+                "  \"microservices/enabled\": false\n" +
+                "}"))
+        })
     })
     @ResponseBody
     public SettingsListResponse getSiteOrPortalDescription(