From 70eca1dc4e04e94eb326482b51ea2617656fa8a8 Mon Sep 17 00:00:00 2001
From: Blake Erickson <o.blakeerickson@gmail.com>
Date: Mon, 30 Aug 2021 11:25:34 -0600
Subject: [PATCH] DEV: Update api docs for search endpoint (#14181)

---
 .../api/schemas/json/search_request.json      | 11 -----
 .../api/schemas/json/search_response.json     | 20 ++++++++-
 spec/requests/api/search_spec.rb              | 42 +++++++++++++++----
 3 files changed, 54 insertions(+), 19 deletions(-)
 delete mode 100644 spec/requests/api/schemas/json/search_request.json

diff --git a/spec/requests/api/schemas/json/search_request.json b/spec/requests/api/schemas/json/search_request.json
deleted file mode 100644
index 0344b0f9299..00000000000
--- a/spec/requests/api/schemas/json/search_request.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "additionalProperties": false,
-  "properties": {
-    "q": {
-      "type": "string"
-    }
-  },
-  "required": [
-    "q"
-  ]
-}
diff --git a/spec/requests/api/schemas/json/search_response.json b/spec/requests/api/schemas/json/search_response.json
index 999fecbc6d0..d0ead9cb734 100644
--- a/spec/requests/api/schemas/json/search_response.json
+++ b/spec/requests/api/schemas/json/search_response.json
@@ -19,6 +19,12 @@
 
       ]
     },
+    "tags": {
+      "type": "array",
+      "items": [
+
+      ]
+    },
     "groups": {
       "type": "array",
       "items": [
@@ -26,7 +32,7 @@
       ]
     },
     "grouped_search_result": {
-      "type": ["object", "null"],
+      "type": "object",
       "additionalProperties": false,
       "properties": {
         "more_posts": {
@@ -86,6 +92,12 @@
 
           ]
         },
+        "tag_ids": {
+          "type": "array",
+          "items": [
+
+          ]
+        },
         "group_ids": {
           "type": "array",
           "items": [
@@ -105,11 +117,17 @@
         "post_ids",
         "user_ids",
         "category_ids",
+        "tag_ids",
         "group_ids"
       ]
     }
   },
   "required": [
+    "posts",
+    "users",
+    "categories",
+    "tags",
+    "groups",
     "grouped_search_result"
   ]
 }
diff --git a/spec/requests/api/search_spec.rb b/spec/requests/api/search_spec.rb
index 4fe9beaa53b..5245e39308a 100644
--- a/spec/requests/api/search_spec.rb
+++ b/spec/requests/api/search_spec.rb
@@ -14,20 +14,48 @@ describe 'groups' do
     get 'Search for a term' do
       tags 'Search'
       consumes 'application/json'
-      expected_request_schema = load_spec_schema('search_request')
-      parameter name: :params, in: :body, schema: expected_request_schema
+      parameter(
+        name: :q,
+        in: :query,
+        type: :string,
+        example: 'api @blake #support tags:api after:2021-06-04 in:unseen in:open order:latest_topic',
+        description: <<~HEREDOC
+          The query string needs to be url encoded and is made up of the following options:
+          - Search term. This is just a string. Usually it would be the first item in the query.
+          - `@<username>`: Use the `@` followed by the username to specify posts by this user.
+          - `#<category>`: Use the `#` followed by the category slug to search within this category.
+          - `tags:`: `api,solved` or for posts that have all the specified tags `api+solved`.
+          - `before:`: `yyyy-mm-dd`
+          - `after:`: `yyyy-mm-dd`
+          - `order:`: `latest`, `likes`, `views`, `latest_topic`
+          - `assigned:`: username (without `@`)
+          - `in:`: `title`, `likes`, `personal`, `seen`, `unseen`, `posted`, `created`, `watching`, `tracking`, `bookmarks`, `assigned`, `unassigned`, `first`, `pinned`, `wiki`
+          - `with:`: `images`
+          - `status:`: `open`, `closed`, `public`, `archived`, `noreplies`, `single_user`, `solved`, `unsolved`
+          - `min_posts:`: 1
+          - `max_posts:`: 10
+          - `min_views:`: 1
+          - `max_views:`: 10
+
+          If you are using cURL you can use the `-G` and the `--data-urlencode` flags to encode the query:
+
+          ```
+          curl -i -sS -X GET -G "http://localhost:4200/search.json" \\
+          --data-urlencode 'q=wordpress @scossar #fun after:2020-01-01'
+          ```
+        HEREDOC
+      )
+      parameter name: :page, in: :query, type: :integer, example: 1
 
       produces 'application/json'
       response '200', 'success response' do
         expected_response_schema = load_spec_schema('search_response')
         schema expected_response_schema
 
-        let(:params) { { 'q' => 'awesome post' } }
+        let(:q) { 'awesome post' }
+        let(:page) { 1 }
 
-        it_behaves_like "a JSON endpoint", 200 do
-          let(:expected_response_schema) { expected_response_schema }
-          let(:expected_request_schema) { expected_request_schema }
-        end
+        run_test!
       end
     end
   end