From 6643f4fa6815f48a1d8815b186d1153dd591b0f5 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <sennyeya@amazon.com>
Date: Tue, 28 Feb 2023 13:19:39 -0500
Subject: [PATCH] Add parameters for the paginated query response and fix
 cursor description.

Signed-off-by: Aramis Sennyey <sennyeya@amazon.com>
---
 plugins/catalog-backend/openapi.yaml | 78 +++++++++++++++++++++++-----
 1 file changed, 65 insertions(+), 13 deletions(-)

diff --git a/plugins/catalog-backend/openapi.yaml b/plugins/catalog-backend/openapi.yaml
index c53a6443ba..9eb1fdd87c 100644
--- a/plugins/catalog-backend/openapi.yaml
+++ b/plugins/catalog-backend/openapi.yaml
@@ -15,7 +15,44 @@ servers:
 components:
   examples: {}
   headers: {}
-  parameters: {}
+  parameters:
+    cursor:
+      name: cursor
+      in: query
+      description: Cursor to a set page of results.
+      required: false
+      schema:
+        type: string
+    fields:
+      name: fields
+      in: query
+      description: Restrict to just these fields in the response.
+      required: false
+      schema:
+        type: string
+    limit:
+      name: limit
+      in: query
+      description: Number of records to return in the response.
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+    sortField:
+      name: sortField
+      in: query
+      description: The fields to sort returned results by.
+      required: false
+      schema:
+        type: array
+        items:
+          type: array
+          items:
+            type: string
+          description: A two-item tuple of [field, order].
+
+      explode: true
+      style: form
   requestBodies: {}
   responses: {}
   schemas:
@@ -211,17 +248,16 @@ components:
         count:
           type: number
       additionalProperties: false
-    EntityFacets:
-      type: array
-      items:
-        $ref: '#/components/schemas/EntityFacet'
+
     EntityFacetsResponse:
       type: object
       properties:
         facets:
           type: object
           additionalProperties:
-            $ref: '#/components/schemas/EntityFacets'
+            type: array
+            items:
+              $ref: '#/components/schemas/EntityFacet'
       required:
         - facets
       additionalProperties: false
@@ -363,7 +399,7 @@ components:
                 that do so in such a way that it breaks semantics.
           description: Metadata fields common to all versions/kinds of entity.
       additionalProperties: false
-    RecursivePartial_Entity_:
+    RecursivePartialEntity:
       type: object
       properties:
         apiVersion:
@@ -392,7 +428,7 @@ components:
           type: string
           description: |-
             A text to show to the user to inform about the choices made. Like, it could say
-            "Found a CODEOWNERS file that covers this target, so we suggest leaving this 
+            "Found a CODEOWNERS file that covers this target, so we suggest leaving this
             field empty; which would currently make it owned by X" where X is taken from the
             codeowners file.
         value:
@@ -424,7 +460,7 @@ components:
           items:
             $ref: '#/components/schemas/AnalyzeLocationEntityField'
         entity:
-          $ref: '#/components/schemas/RecursivePartial_Entity_'
+          $ref: '#/components/schemas/RecursivePartialEntity'
       required:
         - fields
         - entity
@@ -506,11 +542,11 @@ components:
             nextCursor:
               type: string
               description: |-
-                Base64 encoded database query for the next page.
+                The cursor for the next batch of entities.
             prevCursor:
               type: string
               description: |-
-                Base64 encoded database query for the previous page.
+                The cursor for the previous batch of entities.
       additionalProperties: false
   securitySchemes:
     JWT:
@@ -717,11 +753,27 @@ paths:
         - {}
         - JWT: []
       parameters:
-        - in: query
-          name: fields
+        - $ref: '#/components/parameters/fields'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/sortField'
+        - $ref: '#/components/parameters/cursor'
+        - name: fullTextFilterTerm
+          in: query
+          description: Text search term.
           required: false
           schema:
             type: string
+        - name: fullTextFilterFields
+          in: query
+          description: A comma separated list of fields to sort returned results by.
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+          explode: false
+          style: form
+
       requestBody:
         required: true
         content: