Merge pull request #672 from SciCatProject/swap-3430

Update fullquery swagger documentation
SciCatProject · Aug 21, 2023 · b6e19da · b6e19da
2 parents 0560089 + 203d12a
commit b6e19da
Show file tree

Hide file tree

Showing 4 changed files with 129 additions and 25 deletions.
diff --git a/src/common/utils.ts b/src/common/utils.ts
@@ -690,21 +690,96 @@ export const filterDescription =
 }\n \
 </pre>';
 
-export const fullQueryExample =
-  '{ "fields": ["field1", "field2"], "limits": {"limit": 1, "skip": 1, "order": "asc"}}';
+export const fullQueryExampleLimits =
+  '{"limit": 1, "skip": 1, "order": "creationTime:desc"}';
 
-export const fullQueryDescription =
+export const datasetsFullQueryExampleFields =
+  '{"mode":{},"ownerGroup":["group1"],"scientific":[{"lhs":"sample","relation":"EQUAL_TO_STRING","rhs":"my sample"},{"lhs":"temperature","relation":"GREATER_THAN","rhs":10,"unit":"celsius"}]}';
+
+export const fullQueryDescriptionLimits =
   '<pre>\n \
 {\n \
-  "fields?": [ "field1", "field2", ...],\n \
-  "limits?": {\n \
-    "limit": number,\n \
-    "skip": number,\n \
-    "order": [ascending, descending]\n \
-  }\n \
+  "limit": number,\n \
+  "skip": number,\n \
+  "order": [ascending, descending]\n \
 }\n \
 </pre>';
 
+export const datasetsFullQueryDescriptionFields =
+  '<pre>\n  \
+{\n \
+  "mode":{\n \
+    "key": "value",\n \
+  },\n \
+  "text": string, <optional>\n \
+  "creationTime": { <optional>\n \
+    "begin": string,\n \
+    "end": string,\n \
+  },\n \
+  "type": ["type1", ...], <optional>\n \
+  "creationLocation": ["creationLocation1", ...], <optional>\n \
+  "ownerGroup": ["group1", ...], <optional>\n \
+  "keywords": ["keyword1", ...], <optional>\n \
+  "isPublished: boolean,  <optional>\n \
+  "scientific": [ <optional>\n \
+    {\n \
+      "lhs":<metadata_key>>,\n \
+      "relation":["EQUAL_TO_STRING","EQUAL_TO_NUMERIC","GREATER_THAN","LESS_THAN"],\n \
+      "rhs":<metadata_value>,\n \
+      "unit":<unit>,\n \
+    },\n \
+    ...\n \
+  ],\n \
+  "metadataKey": "metadata", <optional>\n \
+  "_id": "item id", <optional>\n \
+  "userGroups": ["group1", ...], <optional>\n \
+  "sharedWith": "email", <optional>\n \
+}\n \
+  </pre>';
+
+export const proposalsFullQueryExampleFields =
+  '{"text": "some text", "proposalId": "proposal_id"}';
+
+export const proposalsFullQueryDescriptionFields =
+  '<pre>\n \
+{\n \
+  "text": string, <optional>\n \
+  "startTime": { <optional>\n \
+    "begin": string,\n \
+    "end": string,\n \
+  },\n \
+  "proposalId": { "regex": string, "options": string }, <optional>\n \
+  "title": { "regex": string, "options": string }, <optional>\n \
+  "firstname": { "regex": string, "options": string }, <optional>\n \
+  "lastname": { "regex": string, "options": string }, <optional>\n \
+  "endTime": { <optional>\n \
+    "begin": string,\n \
+    "end": string,\n \
+  },\n \
+  "userGroups": ["group1", ...],\n \
+}\n \
+  </pre>';
+
+export const samplesFullQueryExampleFields =
+  '{"text": "some text", "metadataKey": "key", "characteristics": [{"lhs":"material","relation":"EQUAL_TO_STRING","rhs":"my material"}]}';
+
+export const samplesFullQueryDescriptionFields =
+  '<pre>\n \
+{\n \
+  "text": string, <optional>\n \
+  "metadataKey": string, <optional>\n \
+  "charactersitics": [ <optional>\n \
+    {\n \
+      "lhs":<property>>,\n \
+      "relation":["EQUAL_TO_STRING","EQUAL_TO_NUMERIC","GREATER_THAN","LESS_THAN"],\n \
+      "rhs":<value>,\n \
+      "unit":<unit>,\n \
+    },\n \
+    ...\n \
+  ],\n \
+}\n \
+  </pre>';
+
 export const parseBoolean = (v: unknown): boolean => {
   switch (v) {
     case true:

diff --git a/src/datasets/datasets.controller.ts b/src/datasets/datasets.controller.ts
@@ -86,6 +86,10 @@ import { CreateDatasetDatablockDto } from "src/datablocks/dto/create-dataset-dat
 import {
   filterDescription,
   filterExample,
+  datasetsFullQueryDescriptionFields,
+  fullQueryDescriptionLimits,
+  datasetsFullQueryExampleFields,
+  fullQueryExampleLimits,
   replaceLikeOperator,
 } from "src/common/utils";
 import { TechniqueClass } from "./schemas/technique.schema";
@@ -558,17 +562,20 @@ export class DatasetsController {
   @ApiQuery({
     name: "fields",
     description:
-      "Define the query conditions using mongoDB syntax as JSON object. It also supports the `text` search, if you want to look for strings anywhere in the dataset. Please refer to mongo documentation for more information about the syntax",
+      "Database filters to apply when retrieving datasets\n" +
+      datasetsFullQueryDescriptionFields,
     required: false,
     type: String,
-    example: {},
+    example: datasetsFullQueryExampleFields,
   })
   @ApiQuery({
     name: "limits",
-    description: "Define further query parameters like skip, limit, order",
+    description:
+      "Define further query parameters like skip, limit, order\n" +
+      fullQueryDescriptionLimits,
     required: false,
     type: String,
-    example: '{ "skip": 0, "limit": 25, "order": "creationTime:desc" }',
+    example: fullQueryExampleLimits,
   })
   @ApiResponse({
     status: 200,

diff --git a/src/proposals/proposals.controller.ts b/src/proposals/proposals.controller.ts
@@ -54,8 +54,10 @@ import { validate, ValidatorOptions } from "class-validator";
 import {
   filterDescription,
   filterExample,
-  fullQueryDescription,
-  fullQueryExample,
+  fullQueryDescriptionLimits,
+  fullQueryExampleLimits,
+  proposalsFullQueryDescriptionFields,
+  proposalsFullQueryExampleFields,
 } from "src/common/utils";
 import { JWTUser } from "src/auth/interfaces/jwt-user.interface";
 
@@ -222,13 +224,22 @@ export class ProposalsController {
       "It returns a list of proposals matching the query provided.<br>This endpoint still needs some work on the query specification.",
   })
   @ApiQuery({
-    name: "filters",
+    name: "fields",
     description:
       "Full query filters to apply when retrieving proposals\n" +
-      fullQueryDescription,
+      proposalsFullQueryDescriptionFields,
+    required: false,
+    type: String,
+    example: proposalsFullQueryExampleFields,
+  })
+  @ApiQuery({
+    name: "limits",
+    description:
+      "Define further query parameters like skip, limit, order\n" +
+      fullQueryDescriptionLimits,
     required: false,
     type: String,
-    example: fullQueryExample,
+    example: fullQueryExampleLimits,
   })
   @ApiResponse({
     status: 200,
@@ -278,10 +289,10 @@ export class ProposalsController {
     name: "filters",
     description:
       "Full facet query filters to apply when retrieving proposals\n" +
-      fullQueryDescription,
+      proposalsFullQueryDescriptionFields,
     required: false,
     type: String,
-    example: fullQueryExample,
+    example: proposalsFullQueryExampleFields,
   })
   @ApiResponse({
     status: 200,

diff --git a/src/samples/samples.controller.ts b/src/samples/samples.controller.ts
@@ -45,8 +45,10 @@ import { IFilters } from "src/common/interfaces/common.interface";
 import {
   filterDescription,
   filterExample,
-  fullQueryDescription,
-  fullQueryExample,
+  fullQueryDescriptionLimits,
+  fullQueryExampleLimits,
+  samplesFullQueryDescriptionFields,
+  samplesFullQueryExampleFields,
 } from "src/common/utils";
 
 @ApiBearerAuth()
@@ -129,13 +131,22 @@ export class SamplesController {
       "It returns a list of samples matching the query provided.<br>This endpoint still needs some work on the query specification.",
   })
   @ApiQuery({
-    name: "filters",
+    name: "fields",
     description:
       "Full query filters to apply when retrieve samples\n" +
-      fullQueryDescription,
+      samplesFullQueryDescriptionFields,
+    required: false,
+    type: String,
+    example: samplesFullQueryExampleFields,
+  })
+  @ApiQuery({
+    name: "limits",
+    description:
+      "Define further query parameters like skip, limit, order\n" +
+      fullQueryDescriptionLimits,
     required: false,
     type: String,
-    example: fullQueryExample,
+    example: fullQueryExampleLimits,
   })
   @ApiResponse({
     status: HttpStatus.OK,