feat: add description to response schema

Author: Jonas Kellerer

lapis2/src/main/kotlin/org/genspectrum/lapis/OpenApiDocs.kt

@@ -13,51 +13,55 @@ import org.genspectrum.lapis.controller.REQUEST_SCHEMA_WITH_MIN_PROPORTION
 import org.genspectrum.lapis.controller.RESPONSE_SCHEMA_AGGREGATED
 
 fun buildOpenApiSchema(sequenceFilterFields: SequenceFilterFields, databaseConfig: DatabaseConfig): OpenAPI {
-    var properties = sequenceFilterFields.fields
+    val filterProperties = sequenceFilterFields.fields
         .map { (fieldName, fieldType) -> fieldName to Schema<String>().type(fieldType.openApiType) }
         .toMap()
 
-    if (databaseConfig.schema.opennessLevel == OpennessLevel.PROTECTED) {
-        properties = properties + ("accessKey" to accessKeySchema)
+    val requestProperties = when (databaseConfig.schema.opennessLevel) {
+        OpennessLevel.PROTECTED -> filterProperties + ("accessKey" to accessKeySchema)
+        else -> filterProperties
     }
 
+    val responseProperties = filterProperties + mapOf(
+        "count" to Schema<String>().type("number"),
+    )
+
     return OpenAPI()
         .components(
             Components().addSchemas(
                 REQUEST_SCHEMA,
                 Schema<String>()
                     .type("object")
                     .description("valid filters for sequence data")
-                    .properties(properties),
+                    .properties(requestProperties),
             ).addSchemas(
                 REQUEST_SCHEMA_WITH_MIN_PROPORTION,
                 Schema<String>()
                     .type("object")
                     .description("valid filters for sequence data")
-                    .properties(properties + Pair(MIN_PROPORTION_PROPERTY, Schema<String>().type("number"))),
+                    .properties(requestProperties + Pair(MIN_PROPORTION_PROPERTY, Schema<String>().type("number"))),
             ).addSchemas(
                 REQUEST_SCHEMA_WITH_GROUP_BY_FIELDS,
                 Schema<String>()
                     .type("object")
                     .description("valid filters for sequence data")
                     .properties(
-                        properties + Pair(
+                        requestProperties + Pair(
                             "fields",
-                            Schema<String>().type("array").items(Schema<String>().type("string")),
+                            fieldsSchema,
                         ),
                     ),
             ).addSchemas(
                 RESPONSE_SCHEMA_AGGREGATED,
                 Schema<String>()
                     .type("object")
-                    .description("aggregated sequence data")
+                    .description(
+                        "Aggregated sequence data. " +
+                            "If fields are specified, then these fields are also keys in the result. " +
+                            "The key 'count' is always present.",
+                    )
                     .required(listOf("count"))
-                    .properties(
-                        properties +
-                            mapOf(
-                                "count" to Schema<String>().type("number"),
-                            ),
-                    ),
+                    .properties(responseProperties),
             ),
         )
 }
@@ -69,3 +73,11 @@ private val accessKeySchema = Schema<String>()
             "There are two types or access keys: One only grants access to aggregated data, " +
             "the other also grants access to detailed data.",
     )
+
+private val fieldsSchema = Schema<String>()
+    .type("array")
+    .items(Schema<String>().type("string"))
+    .description(
+        "The fields to stratify the result by. " +
+            "The response will contain the fields specified here with their respective values.",
+    )

siloLapisTests/test/aggregated.spec.ts

@@ -22,14 +22,15 @@ describe('The /aggregated endpoint', () => {
         });
 
         const resultWithoutUndefined = result.map((aggregatedResponse: AggregatedResponse) => {
-          const responseWithoutUndefined: Partial<AggregatedResponse> = {};
-          for (const [key, value] of Object.entries(aggregatedResponse)) {
-            if (value !== undefined) {
-              // @ts-ignore
-              responseWithoutUndefined[key] = value;
-            }
-          }
-          return responseWithoutUndefined;
+          return Object.entries(aggregatedResponse)
+            .filter(([, value]) => value !== undefined)
+            .reduce(
+              (accumulatedObject, [key, value]) => ({
+                [key]: value,
+                ...accumulatedObject,
+              }),
+              {} as AggregatedResponse
+            );
         });
 
         expect(resultWithoutUndefined).to.have.deep.members(testCase.expected);