docs(graphql): rewrote search.md (#1130)

* docs(graphql): rewrote search.md
docs(graphql): added pagination and filter docs for gql

Squash of both commits:
(cherry picked from commit 2268fa0510b32b27f2c1f71e9889ec769877553b)
(cherry picked from commit c96adc88b2fb9edff90e7e4b01a8885511ceb0df)
Signed-off-by: Catalin Hofnar <catalin.hofnar@gmail.com>

Some additional updates by Andrei Aaron to keep up with the changes on main.
Also add more comments to schema.graphql

Signed-off-by: Andrei Aaron <aaaron@luxoft.com>

* style: run a graphql schemma linter as a github workflow

Signed-off-by: Andrei Aaron <aaaron@luxoft.com>

---------

Signed-off-by: Andrei Aaron <aaaron@luxoft.com>
Co-authored-by: Catalin Hofnar <catalin.hofnar@gmail.com>

.github/workflows/gqlgen.yaml

@@ -1,7 +1,8 @@
-name: "GQL generation"
+name: "GQL generation and linting"
 
 # Validate gqlgen works
 # Validate there are no uncommitted changes after running gqlgen
+# Lint the graphql schemma
 
 on:
   push:
@@ -34,3 +35,15 @@ jobs:
       - name: Verify uncommitted files
         run: |
             make verify-gql-committed
+  gqllint:
+    name: Check GQL schemma follows best practices
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install dependencies
+        run: |
+          cd $GITHUB_WORKSPACE
+          npm install graphql-schema-linter graphql
+      - name: Lint the graphql schemma
+        run: |
+          $(npm bin)/graphql-schema-linter pkg/extensions/search/*.graphql